diff --git a/.github/ISSUE_TEMPLATE/mcp-ticket.md b/.github/ISSUE_TEMPLATE/mcp-ticket.md
new file mode 100644
index 00000000..d22c4b91
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/mcp-ticket.md
@@ -0,0 +1,23 @@
+---
+name: MCP agent-loop ticket
+about: Filed by the implementer/tester agent loop (see the iterate repo's CLAUDE.md) — not for human bug reports, use "Bug report" for those.
+title: ""
+labels: ["owner:implementer"]
+---
+
+**tool/endpoint:** which MCP tool or method this concerns
+
+**repro:** exact call made (tool name + params, or command run)
+
+**expected:**
+
+**actual:**
+
+<!--
+Status is tracked by label (status:fixed-pending-verify, status:needs-info,
+status:needs-approval, status:verified) plus the issue's open/closed state
+and close reason (completed = verified, not planned = wontfix/duplicate).
+Owner is tracked by label (owner:implementer, owner:tester, owner:don) —
+exactly one at a time, swapped by whoever hands the ticket off.
+Notes and verify-notes are ordinary comments on the thread, in order.
+-->
diff --git a/CLAUDE.md b/CLAUDE.md
index c7066661..3a6e311c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -154,6 +154,10 @@ docs/WORKSPACES.md, and docs/proposals/server-workspaces-complete.md for the lat
   rooted at the library rather than the workflow file. The library is `DW_PROMPT_DIR` /
   `--prompt-dir`, else `./prompts` if it exists, else found by walking up from the
   workflow file's directory
+- A step's `result.subfolder` names a subfolder of the run directory for that step's
+  files - by convention `final` for the deliverable and `intermediate` for the rest; any
+  relative path (`shots/act-1`); `variable:`/`item:` allowed; no default. Mechanics under
+  *Result subfolders* in Critical Gotchas
 - A step carrying `for_each` (a list, or `variable:` naming one) is expanded by
   `expand_for_each` (`dw/for_each.py`) into one ordinary step per entry, named
   `<step>@<entry name or index>`, immediately after `replace_variables` in
@@ -298,6 +302,36 @@ same reason - default setup cannot load a pack.
   `JobManager.realized` finds the file. `exports` is a reserved workspace name:
   `POST /api/jobs/{id}/export` gathers one finished job into
   `<workspace>/exports/<job id>/` and `GET /exports/<job id>.zip` streams it.
+- **Result subfolders**: a step's `result.subfolder` (`dw/subfolders.py`) puts its files
+  in a subfolder of the run directory - `<run>/final/x.mp4` - by convention `final` or
+  `intermediate`; the engine treats no name specially and there is no default.
+  `Workflow.step_output_dir` computes the directory once and hands it to both
+  `Result.save` and the pipeline wrapper, so a chain's `save_segments` spill follows it.
+  Shape is `SUBFOLDER_PATTERN` (the `output:` segment rule, so a subfolder is
+  `output:`-addressable up to `OUTPUT_REFERENCE_PATTERN`'s seven-segment ceiling),
+  checked by `subfolder_errors` in `validation_errors` after
+  `for_each` expansion and again at run time; containment is `validate_output_path`
+  against the run directory. Manifest entries and `step_end` carry `subfolder`.
+  `split_run_path` finds the run id anywhere in a path, so `strip_run_id` still groups a
+  workflow's runs. Gallery entries carry it too; `GET /api/gallery?subfolder=` and MCP
+  `list_gallery(subfolder=)` filter on it. The web UI reads the field only:
+  the gallery page offers a subfolder pick once any entry has one, and the
+  job page sections results under `final/` / `intermediate/` headings (or
+  whatever the step named) (`sectionBySubfolder`, `ui/src/lib/results.ts`),
+  unchanged for a run that chose none. `file_base_name` may not contain a
+  separator -
+  it is a name, not a path.
+  Every `workflows/templates/**` file with two or more saving steps
+  marks each one `final`/`intermediate` (`tests/test_template_subfolders.py` pins the rule;
+  `dw/workflows/` builtins stay unmarked - a role is the parent's to assign). That moved
+  the templates' outputs into `<run>/final/` and `<run>/intermediate/`: an
+  `output:<template>/latest/x` reference keeps resolving but stops advancing past the last
+  pre-change run (`keep_output` is the stable form), and a seeded template's first run
+  after the change regenerates rather than hitting the step cache (the key includes
+  `result`). Those two, and a stray `subfolder` key becoming live, are the release-note
+  items beside the `shots` list change. Gallery names for a template's runs now read
+  `<template>/<run id>/final/<file>`, so an `output:` reference built from one carries the
+  `final/` segment
 - **Step cache**: a process-wide singleton (`dw/step_cache.py`) consulted by every `Workflow.run`, including server jobs; entries are keyed by `(workflow id, step name)` and validated against the output
   *root*, never the per-run directory - a run directory is new every execution and would
   defeat the cache; disabled entirely when the workflow sets no `seed`; a hit reports the earlier run's files with `reused: true` and writes nothing new; `memory clear` drops it. This is why "Run again" on a seeded workflow finishes instantly and generates nothing - the job page says so when every step was reused, and `POST /api/jobs/{id}/rerun` with `{"new_seed": true}` (MCP `rerun_job(new_seed=True)`) draws a fresh seed into the workflow's seed variable, which is the way to get a different image
diff --git a/docs/MCP.md b/docs/MCP.md
index 68500bd9..fd4a4670 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -222,11 +222,11 @@ when no single workflow covers it.
 | `list_tasks()` | — | List every task command a workflow's task step can name |
 | `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 |
+| `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). `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_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)` | `limit` | List generated output files, newest first. A name is `<workflow>/<run id>/<file>`; 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 |
+| `list_gallery(limit=50, subfolder=None)` | `limit`, `subfolder` | 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 |
 | `get_gallery_metadata(name, envelope=False)` | `name` | Get the metadata embedded in a generated file: 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 |
 
 ### Media
@@ -283,7 +283,7 @@ references written in the same session.
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
 | `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 |
-| `get_job(job_id)` | `job_id` | Get a job's status, warnings, output manifest, error and traceback. A running job also carries `progress` (below) |
+| `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 |
 | `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 |
diff --git a/docs/SERVER.md b/docs/SERVER.md
index bdcadc0a..5a0ef570 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -54,6 +54,9 @@ load entirely.
   progress, per-step denoising ticks, what each step is doing when it is not
   denoising (loading a model, decoding, saving), and its result files as
   they land.
+  A run whose steps chose a `result.subfolder` shows its results under
+  `final/` and `intermediate/` headings (or whatever the step named), the
+  deliverable first; one that chose none shows them as before.
   Jobs can be cancelled mid-denoise and re-run with one click. A finished
   job's **Export** button gathers the run into the workspace's `exports/`
   on the server (`POST /api/jobs/{id}/export`) and downloads it as one zip -
@@ -78,7 +81,10 @@ load entirely.
   the form view.
 - **Gallery** — everything in the selected workspace's output directory,
   which the engine lays out as `<workflow>/<run id>/`. The folder filter groups a workflow's runs
-  together rather than listing each run separately, and each run directory
+  together rather than listing each run separately, and a **subfolder** pick
+  beside the text filter - offered once any output landed in one - narrows
+  the grid to `final/`, `intermediate/` or whatever a step's
+  `result.subfolder` named; each run directory
   also holds a `manifest.json` describing what produced it (see
   [Workspaces](WORKSPACES.md#runs)). Images generated with
   `embed_metadata` carry their full workflow definition and seed; **open as
@@ -138,7 +144,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. |
 | `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`. 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}` | 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 |
 | `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 |
@@ -162,10 +168,11 @@ Every event in the stream carries a `seq` and an `event` name:
 | `memory` | device memory after a run | `info` |
 | `run_start` | the run directory is chosen, before the first step | `run_id`, `identity`, `run_dir` |
 | `workflow_start` | the run begins | `workflow`, `total_steps`, `steps`, `seed` |
-| `step_start` / `step_end` | each step | `step`, `index`, `total_steps`; `files` at the end. A step served from the step cache adds `reused: true` to `step_end`, and its `files` are the earlier run's files rather than newly written ones |
+| `step_start` / `step_end` | each step | `step`, `index`, `total_steps`; `files` and `subfolder` at the end. A step served from the step cache adds `reused: true` to `step_end`, and its `files` are the earlier run's files rather than newly written ones |
 | `iteration_start` | each argument combination in a step | `step`, `iteration`, `total_iterations` |
 | `pipeline_step` | each denoise step | `step`, `total_steps`. Emitted for a pipeline that takes a `callback_on_step_end`, and for a `ModularPipeline` (H3, LTX-2, Qwen-Image), which takes none - there the denoise block's own progress bar is what reports |
 | `phase` | the step changes what it is doing | `phase`, `detail` |
+| `pipeline_released` | a step with `release_pipeline` drops its pipeline | `step`, `index`, `gpu_memory_allocated_mb` and `gpu_memory_allocated_before_mb` (both `null` where the backend cannot say). Emitted between the step's generation and its files being written, which is where the release happens - so the ordering is readable off the event stream rather than by trying to poll memory through a sub-second write |
 | `workflow_end` | the run finishes | `manifest` |
 
 A step spends most of its wall clock outside the denoise loop, and
@@ -295,7 +302,13 @@ The editor's forms come from these; they are just as usable from scripts:
   queue an enhancement as an ordinary job whose saved text file is the
   result
 - `GET /api/gallery`, `GET /api/gallery/{name}/metadata`,
-  `DELETE /api/gallery/{name}` — outputs and their embedded metadata
+  `DELETE /api/gallery/{name}` — outputs and their embedded metadata. Each
+  gallery entry carries `folder` (the workflow identity, the run id dropped)
+  and `subfolder` (what followed the run id - the `final`/`intermediate` a
+  step's `result.subfolder` chose, `''` when it chose none); `?folder=` and
+  `?subfolder=` filter independently, and the reply's `folders` and
+  `subfolders` list every distinct value over the whole tree, `''` always a
+  member of each so root-level files stay selectable
 - `GET /api/gallery/{name:path}/download` — download an output file
 - `POST /api/gallery/archive` — `{"names": [...]}` (1-1000) bundles a
   multi-file selection into one zip, named by each file's gallery-relative
@@ -376,8 +389,13 @@ The editor's forms come from these; they are just as usable from scripts:
   started) alongside the live `version`/`commit`, so a revert has a
   concrete before/after to compare
 - `GET /api/memory`, `GET /api/health` — worker VRAM/RAM stats and liveness;
-  health also reports `hostname`, `device` and whether `mcp` is mounted, so a
-  remote client can tell which machine answered
+  memory answers `live` (whether `info` was measured by this call), `stale`,
+  `reason` (`job_running`, `worker_stopped`, `worker_busy`,
+  `worker_unreachable`) and `age_seconds`, so a cached reading is never
+  mistaken for the worker's memory now - `info: null` means nothing has been
+  measured because nothing is resident. health also reports `hostname`,
+  `device` and whether `mcp` is mounted, so a remote client can tell which
+  machine answered
 - `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
diff --git a/docs/TASKS.md b/docs/TASKS.md
index b6d31fe4..a1339842 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -205,6 +205,8 @@ video generation" in the workflow guide):
 | `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) |
 | `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 |
+| `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`) |
 
 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
@@ -280,6 +282,21 @@ a continuous bed under the whole cut: `slice_audio` a few seconds of tone out of
 a shot, [`loop_audio`](#loop_audio) it to the length of the cut, `mix_audio` it
 under the episode and `pair_audio` it back onto the picture.
 
+Levels are the other thing a cut has to reconcile, and no fade control can
+touch it. Shots generated independently land wherever the model put them - two
+shots of one scene, same template, same cast, measured `peak_dbfs` -2.65 and
+-12.56 - and each reads as fine on its own, because a shot is only wrong
+*relative to what it is cut against*. Butt-joined, that is a 10 dB drop at the
+cut, and it is not an artifact *at* the seam that a fade could smooth: it is
+either side of it. `match_levels` scales each track before the join -
+`"rms"` matches perceived level, which is usually what "make these sound the
+same" means, and `"peak"` matches the loudest sample, which is the safer
+choice on material with big transients. A shot whose gain would clip at the
+target is held just below full scale and the log says so. Left off - the
+default, so nothing existing changes - a spread of 6 dB or more across the
+tracks being joined is logged as a warning rather than passing in silence.
+`dissolve_videos` takes the same pair.
+
 ### dissolve_videos
 
 Join videos with a cross-dissolve at every seam, and fade the whole piece in
@@ -311,6 +328,8 @@ montage cut to a score wants:
 | `fade_out_frames` | No | Frames over which the last video sinks into it (default: 0) |
 | `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 |
+| `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`) |
 
 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/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 2c3aa3e2..f26d58b3 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -512,6 +512,37 @@ workflow.
   `reference-to-video` and `dialogue-short` templates). The `identity-referenced`
   trait in the listing marks the workflows that take one.
 
+### Saying which output is the deliverable
+
+A run writes everything into one directory, so a finished episode sits
+beside the twenty scratch files that went into it. A step's `result` block
+can name a subfolder of the run directory for its files:
+
+```json
+"result": { "content_type": "video/mp4", "subfolder": "final" }
+```
+
+The convention is two names: `final` for a step whose output the user will
+be shown, `intermediate` for everything else. The engine treats no name
+specially and applies no default - a step that says nothing writes to the
+run's root as it always has - but the gallery, `get_job` and `list_gallery`
+all carry the value, so a consumer that follows the convention can tell the
+deliverable from the scratch without knowing the workflow. Mark every saving
+step of a multi-step workflow; a one-step workflow needs nothing.
+
+The shipped templates follow it: every template with two or more saving
+steps marks each one, so a workflow copied from a template starts with the
+roles in place.
+
+The value is a relative path of any depth (`shots/act-1`), may be a
+`variable:` or, inside a `for_each` step, an `item:` reference, and follows
+the `output:` segment rule - each segment starts with a letter, digit or
+underscore; `..`, a backslash and a leading `.` are refused - so every
+subfolder written is one a later workflow can name:
+`output:dialogue-short/latest/final/episode.mp4`. A bad value is a
+validation error at its JSON path. `file_base_name` is a name, not a path:
+a separator there is refused, and `subfolder` is the way to place a file.
+
 ### Being found next time
 
 The catalog derives each entry's `shape` — one of `image`, `image-set`,
@@ -536,12 +567,15 @@ never derived — leave it absent until a run has been measured.
 "result": {
     "content_type": "image/jpeg",
     "save": true,
-    "file_base_name": "custom_prefix"
+    "file_base_name": "custom_prefix",
+    "subfolder": "final"
 }
 ```
 
 Supported content types: `image/jpeg`, `image/png`, `image/webp`, `image/gif`, `video/mp4`, `audio/wav`, `audio/flac`, `audio/mpeg` (mp3), `audio/ogg`, `audio/opus`, `audio/aiff`, `application/json`, `text/plain` (plus the common aliases `audio/x-wav`, `audio/mp3`, `audio/vorbis`).
 
+`subfolder` places the step's files in a subfolder of the run directory - see *Saying which output is the deliverable* above. `file_base_name` may not contain a path separator.
+
 For video, add `"fps": 8`. For audio, add `"sample_rate": 44100` when the waveform doesn't
 already carry a rate of its own (a declared rate always wins). Setting `embed_metadata: true`
 on an image result embeds the step's model name and arguments as generation metadata -
diff --git a/docs/proposals/mcp-job-notifications.md b/docs/proposals/mcp-job-notifications.md
new file mode 100644
index 00000000..5d2a2482
--- /dev/null
+++ b/docs/proposals/mcp-job-notifications.md
@@ -0,0 +1,153 @@
+# Proposal: gapless job-completion signaling across the MCP bridge
+
+Status: **not started** - design only, written after tracing the current
+`wait_for_job` / event-log path end to end. No code changes yet.
+
+## The problem, as reported
+
+An agent driving `dw` over MCP (a Claude Code session, interactively or via a
+`ScheduleWakeup`-paced loop) submits a job and then polls for it to finish.
+In practice that active loop sometimes fails to notice the terminal
+transition - a completed run, or a worker OOM-kill - promptly. The job
+*does* reach a terminal state server-side; the agent just doesn't reliably
+find out from the next poll.
+
+## Why the current contract allows that gap
+
+`wait_for_job` (`dw_mcp/diagnose.py:147-229`) polls `GET /api/jobs/{id}`
+every `WAIT_POLL_SECONDS` (1.0s) and returns as soon as `status` is one of
+`succeeded`/`failed`/`cancelled`, capped at `MAX_WAIT_SECONDS` (55s) per
+call - the comment there explains the cap exists because no MCP client
+holds a tool call open longer than roughly one generation's runtime. A
+caller whose job outlives one call gets `still_running: true` back and is
+expected to call again.
+
+That contract only tracks a *snapshot* of `status`. It never tells the
+caller what it has and hasn't seen, so nothing about it prevents this
+sequence: call N times out at `still_running: true`; the caller's own
+bookkeeping (a `ScheduleWakeup` cadence, a retry decision made by the model)
+drifts, skips a beat, or gets reset; call N+1 starts a fresh 55s window with
+no memory of call N. If the terminal transition happened in the seam
+between "the loop should have re-invoked" and "the loop actually did," there
+is no cursor tying the two calls together that would let the caller prove
+to itself it never missed anything - it's trusting its own retry discipline,
+which is exactly the thing that reportedly drifts.
+
+The server side, by contrast, already has what's missing. `dw/server/jobs.py`
+keeps a per-job append-only event log; `GET /api/jobs/{id}/events` (SSE,
+`dw/server/app.py:1033-1069`) and its polling twin `GET
+/api/jobs/{id}/event-log` both already support resuming from a sequence
+number (`Last-Event-ID` / an offset param), and `ui/src/lib/api.ts`'s
+`streamJobEvents()` already resumes this way on reconnect. `wait_for_job`
+just doesn't use any of it - it was built against the coarse `GET
+/api/jobs/{id}` status field, not the event log the SSE route already reads.
+
+A worker OOM-kill is, separately, already detected reliably:
+`WorkerManager.crash_details()` (`dw/repl_worker.py`) inspects the dead
+worker's exit code and identifies a negative code consistent with SIGKILL
+within one liveness-poll interval (~1s) of the process dying; `_consume_results`
+(`dw/server/jobs.py:1019-1082`) converts that into a `failed` job with a
+human-readable reason string. So the job never gets stuck in `running` -
+the gap is purely that this distinction (OOM vs. an ordinary pipeline
+exception vs. cancellation) is flattened into one free-text `error` string
+by the time a caller sees it, so an agent can't branch on it without parsing
+prose.
+
+## Design
+
+### 1. Cursor-based `wait_for_job`
+
+Change `wait_for_job` to read the same event log the SSE/event-log routes
+already read, keyed by sequence number, instead of the bare status field:
+
+- New optional parameter `since_seq` (default `0`).
+- Each call advances through `job.events_after(since_seq)` until either a
+  terminal event appears or the 55s budget expires.
+- Response gains `last_seq` (the highest sequence number the call actually
+  observed) alongside `status`/`still_running`.
+- The documented contract for a caller: **always pass the `last_seq` you
+  were given into your next call.** Doing so makes it structurally
+  impossible to skip a terminal event - the next call resumes exactly where
+  the last one left off, rather than re-asking "what's the status *now*"
+  and trusting that "now" didn't skip past "finished" in between. This
+  turns a timing bug into a logic property: correctness no longer depends
+  on how promptly the caller re-invokes, only on whether it ever stops
+  calling at all (which is a visible, reportable "I gave up," not a silent
+  miss).
+- `get_job_events` (the existing paged event reader) takes the same
+  `since_seq` / `last_seq` pairing for consistency, replacing its current
+  offset-based paging.
+
+### 2. Explicit `failure_kind`
+
+Add a `failure_kind` field, populated at the same point
+`_consume_results` already classifies a dead worker or a `worker_crashed`
+message:
+
+- `"oom"` - negative exit code consistent with SIGKILL (today's
+  `crash_details()` heuristic)
+- `"crash"` - worker died some other way (different signal, non-zero exit)
+- `"error"` - the pipeline raised inside a live worker
+- `"cancelled"` - explicit cancellation
+- absent/`null` on success
+
+Additive to the existing `status`/`error`/`traceback` fields - a new
+nullable column in `jobs.sqlite`, no migration of existing rows needed
+beyond a default of `null`. This lets a caller branch on `failure_kind`
+(e.g. suggest a smaller batch or lower resolution on `"oom"`) instead of
+pattern-matching the free-text reason string.
+
+### 3. Document the recommended loop
+
+Once the cursor exists, the failure mode this proposal is about becomes a
+caller-discipline problem with a mechanical fix: always thread `last_seq`
+forward, whether the next call happens immediately (blocking retry) or
+after a `ScheduleWakeup` delay. Document this explicitly in
+`dw_mcp/CLAUDE.md` and the `Authoring a workflow from an agent` section of
+`docs/WORKFLOW_GUIDE.md` (or wherever job-waiting guidance already lives)
+rather than leaving each session to reconstruct a polling loop from first
+principles: submit → `wait_for_job(since_seq=0)` → if `still_running`,
+re-call with the returned `last_seq` → on terminal status, branch on
+`failure_kind`.
+
+### Rejected: server-initiated push (webhook/callback)
+
+`dw.serve` calling out to the agent when a job finishes was considered and
+dropped. There is no MCP-native or Claude-Code-native inbound channel that
+lets an MCP server wake a specific idle session; building one would mean
+standing up a listener process outside both `dw` and the MCP protocol, which
+just relocates today's polling problem onto a different piece of
+infrastructure rather than removing it. The cursor fix above removes the
+actual defect (a possible-but-unprovable miss) without adding a process,
+a port, or a new failure mode of its own.
+
+## Scope / non-goals
+
+- No change to job semantics, `TERMINAL_STATES`, or the worker crash-detection
+  heuristic itself - this only exposes what's already computed, more
+  precisely and with a resumable cursor.
+- No change to the SSE endpoint's own framing; it already resumes by
+  sequence number. This brings `wait_for_job`/`get_job_events` up to the
+  same standard, it doesn't change the standard.
+- Not a UI change. `ui/src/lib/api.ts`'s `streamJobEvents()` already
+  resumes by `seq`; this keeps the MCP surface consistent with it rather
+  than introducing a second convention.
+
+## Testing
+
+- Server: a test that a SIGKILL'd worker's job record carries
+  `failure_kind: "oom"`, alongside the existing crash-detection tests.
+- MCP: a test that two sequential `wait_for_job` calls, with the cursor
+  passed forward, never re-report an event already seen and never skip a
+  terminal one - including the case where the terminal event lands in the
+  gap between the two calls (assert on the boundary, not just the happy
+  path).
+
+## Open question for whoever picks this up
+
+Whether `since_seq`/`last_seq` should be *required* (no default of `0`) so
+that a caller cannot silently opt back into the old snapshot behavior by
+omitting it. Leaning towards optional-with-a-default for backward
+compatibility with any existing caller that only reads `status`, but a
+required cursor is the stronger guarantee if there's an appetite for a
+breaking MCP-surface change here.
diff --git a/docs/proposals/output-folders.md b/docs/proposals/output-folders.md
index b080168a..776e08d2 100644
--- a/docs/proposals/output-folders.md
+++ b/docs/proposals/output-folders.md
@@ -1,6 +1,8 @@
-# Proposal: folders for a job's outputs
+# Design: subfolders for a run's outputs
 
-Status: **proposed, not implemented**. Written for MCP feedback ticket T016.
+Status: **all four stages (engine, server/MCP, steering, UI) implemented**. Written for MCP feedback ticket T016;
+reviewed against the code on 2026-09-12. Decisions taken in that review are
+marked *decided*.
 
 ## The ask, as filed
 
@@ -22,39 +24,39 @@ each file name. The consumer of that run - an agent deciding what to show
 the user, or a person opening the gallery - has to know the workflow to know
 which file is the deliverable.
 
-## Why this is a proposal and not an edit
+## Why this needed a design and not an edit
 
-A destination folder is a new field in the workflow schema, which means it
-is a concept every consumer has to learn and every surface has to carry. But
-the reason it is a proposal rather than an edit is narrower than that: **the
-output tree already has a layer with the meaning this wants.**
+A destination folder is a new field in the workflow schema, so every
+consumer has to learn it and every surface has to carry it. But the reason
+it needed deciding is narrower: **the output tree already has a layer with
+the meaning this wants**, and three things read that tree by position.
 
-A run writes to `<output root>/<workflow identity>/<run id>/`, and three
-separate things read that shape by position:
+A run writes to `<output root>/<workflow identity>/<run id>/`:
 
 - `strip_run_id` (`dw/runs.py`) turns `ltx2/Gyre/20260905-181530-a1b2c3d4/
   still-0.png` into the gallery folder `ltx2/Gyre`, which is how a workflow
-  run fifty times is one entry in the folder filter rather than fifty.
+  run fifty times is one entry in the folder filter rather than fifty. It
+  does this by testing whether the *last* directory segment is a run id.
 - `output:` references are `<workflow identity>/<run id>/<file>`, with
   `latest` allowed in the run-id position (`resolve_output_reference`).
 - The manifest, and `workflow.json` beside it, sit at the root of the run
   directory and describe everything in it.
 
-Adding a folder *inside* a run directory puts a segment between the run id
-and the file name, and every one of those three readers has to be told which
-segment is which. Getting that wrong is not a cosmetic bug: `strip_run_id`
-would start reporting `ltx2/Gyre/final` and `ltx2/Gyre/intermediate` as two
-unrelated workflows in the gallery filter, and an `output:` reference that
-worked yesterday would resolve to nothing. That is the part that needs
-deciding before anything is written.
+A folder *inside* a run directory puts a segment between the run id and the
+file name. As the code stands, `strip_run_id` on
+`ltx2/Gyre/<run>/final/x.mp4` returns `ltx2/Gyre/<run>/final` - the run id
+is no longer the last segment, so the gallery filter would gain one entry
+per run. That is the part that had to be decided before anything was
+written. The other two readers turn out to need nothing (below).
 
 There is also a question the ticket settles one way and the existing code
-settles the other, covered under [Open questions](#open-questions): the
-workflow and prompt libraries do not actually enforce one level.
+settles the other: the workflow and prompt libraries do not enforce one
+level, so "consistent with them" means not enforcing one here either.
 
-## The shape
+## The field
 
-A step's `result` block names the folder its files are written into:
+A step's `result` block names the subfolder of the run directory its files
+are written into:
 
 ```json
 {
@@ -62,34 +64,143 @@ A step's `result` block names the folder its files are written into:
   "task": { "command": "concat_videos", "arguments": { "...": "..." } },
   "result": {
     "content_type": "video/mp4",
-    "folder": "final"
+    "subfolder": "final"
   }
 }
 ```
 
-- `folder` is optional. Without it, files are written where they are written
-  today: at the root of the run directory. **Every existing workflow keeps
-  working unchanged, and a workflow that never sets `folder` is
-  indistinguishable from one written before this existed.**
-- The value is a relative path validated the way every other
-  workflow-supplied path segment is - through `validate_output_path` against
-  the run directory, so `../` and absolute paths are refused rather than
-  escaping into another run.
-- It may carry a `variable:` reference, so a caller can route a run's
-  outputs without editing the workflow.
-- It is per step, not per workflow: the point is that one run's steps land
-  in different places.
+- **Named `subfolder`, on every surface** (*decided*). It is literally a
+  subfolder of the run directory. The word `folder` was rejected because a
+  gallery entry's `folder` already means the workflow identity, and an
+  author who set `"folder": "final"` would have read back
+  `folder: "ltx2/Gyre"` beside some other key; `group` was rejected because
+  `for_each` documentation already uses "group" for what `gather:` reads.
+  One word, same meaning, in the schema, the manifests, the gallery and the
+  query string.
+- Optional. Without it, files are written where they are written today: at
+  the root of the run directory. **Every existing workflow keeps working
+  unchanged, and a workflow that never sets `subfolder` writes
+  byte-identical paths to one written before this existed.**
+- A relative path of any depth (*decided*; see the first open question,
+  now closed). Its *shape* is checked by a segment pattern,
+  `^[\w][\w.-]*(/[\w][\w.-]*)*\Z` - the same rule a segment of an
+  `output:` reference obeys (`OUTPUT_REFERENCE_PATTERN`), so every
+  subfolder the engine writes is one a later workflow can name. That
+  refuses `..`, a leading or trailing `/`, an empty segment, a segment
+  beginning with `.` or `-`, and `\` - which matters because
+  `DANGEROUS_PATTERNS` (`dw/security.py`) does not list a backslash, so
+  `"final\\x"` would otherwise be one directory on POSIX and two on
+  Windows. Its *containment* is then checked by `validate_output_path`
+  against the run directory, which is what guards symlinks. One ceiling
+  follows from the alignment: `OUTPUT_REFERENCE_PATTERN` allows seven
+  segments in total, so a subfolder deep enough to push
+  `<identity>/<run>/<subfolder>/<file>` past seven is writable but not
+  `output:`-addressable. Documented, not enforced.
+- Substitution applies as it does to the rest of the step: `variable:` so a
+  caller can route a run's outputs without editing the workflow, and
+  `item:` inside a `for_each` template so members can land in their own
+  places (`"subfolder": "item:subfolder"`). This is the case that argues
+  against a depth limit - `shots/act-1` is a natural thing to want.
+- Per step, not per workflow: the point is that one run's steps land in
+  different places.
+- **No default, ever** (*decided*). A one-step workflow's output is by
+  definition the deliverable, but defaulting it to `final` would move
+  every such workflow's files on upgrade and silently stop any stored
+  `output:` reference from advancing.
 
 The convention the tooling steers toward is two names, `final` and
 `intermediate` - see [Steering](#steering-consumers-toward-it). The engine
 does not know those names or treat them specially; a workflow that wants
 `shots/` and `audio/` gets them.
 
+### Where the checks live
+
+Schema validation runs *before* substitution, so a schema `pattern` on
+`subfolder` would reject the `"variable:dest"` and `"item:subfolder"` this
+design wants. The schema therefore gets a `description` only. The shape
+check runs in two places:
+
+- **Statically**, as a post-expansion pass in `validation_errors`
+  (`dw/workflow.py`), beside `previous_result_reference_errors` - a new
+  `subfolder_errors` in a small module of its own, reporting the JSON path
+  of the offending `result` block, so `dw.validate` and `POST /api/validate`
+  name it before anything is queued. It runs on the substituted, expanded
+  definition, so an `item:`-driven subfolder is checked per member.
+- **At run time**, where the step's target directory is computed (below),
+  for a definition that reached the engine without validation.
+
+### `file_base_name` may no longer contain a separator
+
+`"file_base_name": "final/"` passes `validate_string_input` and
+`validate_output_path` today and then fails at `open()` because the
+directory does not exist - a latent crash, not a feature. With a real
+placement field it becomes an error naming `subfolder` as the way to do
+it, checked in the same two places. No shipped workflow (`workflows/`,
+`dw/workflows/`, `plugins/`) uses a separator there.
+
 ## What each surface does with it
 
-### The run directory and the manifest
+### The engine (`dw/result.py`, `dw/workflow.py`, `dw/runs.py`)
+
+- **The step's target directory is computed once, in `workflow.py`**, not
+  inside `Result.save`. A new `Workflow.step_output_dir(step_definition)`
+  returns `effective_output_dir` joined with the step's `subfolder`
+  (shape-checked, then `validate_output_path(joined, effective_output_dir)`,
+  then created), or `effective_output_dir` itself when there is none. It is
+  handed to *both* `Result.save` as its `output_dir` and to
+  `create_step_action` as the pipeline's `output_dir` (`workflow.py`
+  ~1003/1032/962). The second matters: a chain pipeline's `save_segments`
+  spill (`dw/pipeline_processors/chain.py`, `SegmentSpill`) writes through
+  the pipeline's `output_dir`, so without this a `keep_segments: true`
+  step's segments would land at the run root while its video landed in
+  `final/`. `Result.save` itself is unchanged apart from refusing a
+  separator in `file_base_name`: names stay
+  `{workflow}-{step}.{i}-{j}.{k}.ext`, deduplication stays per path.
+- The manifest entry `workflow.py` appends per step gains
+  `"subfolder": <value or "">`, and so does the `step_end` event it emits
+  - the job page groups from `step_end` events while a job runs and
+  confirms from the manifest at the end (`ui/src/lib/results.ts`), so a
+  field only on the manifest would appear only once the job finished. A
+  step-cache hit keeps the *definition's* subfolder while its files stay
+  the earlier run's absolute paths, exactly as `reused` entries work now;
+  the cache compares the whole step snapshot including `result`, so a
+  changed subfolder misses.
+- **Sub-workflows.** A `workflow` step's own `result` block governs only
+  what the *parent* saves from the child's return value (`dw/step.py`); the
+  child's steps save through their own `result` blocks into the inherited
+  run directory, and the parent rolls their entries up verbatim. So a
+  parent's `subfolder` never prefixes the child's steps - each step places
+  its own files. This is the right reading (a child is a step list, not a
+  folder) and needs no code, but it is stated because the alternative is
+  plausible.
+- `dw/runs.py` gains `split_run_path(relative) -> (identity, run_id,
+  subfolder)`: locate the first directory segment matching
+  `RUN_ID_PATTERN` (`^\d{8}-\d{6}-[0-9a-f]{8}(-\d+)?$`); identity is
+  everything before, subfolder everything after. A workflow *file* named
+  in that shape would produce a matching identity segment - unsupported,
+  not impossible. `strip_run_id` becomes a thin wrapper returning the
+  identity, so its callers and tests hold. A path with no run id (flat
+  layout) returns its directory as identity and `""` as subfolder, as
+  today.
+
+### The two manifests
+
+There are two, and they record files differently:
+
+- `manifest.json` in the run directory records files relative to the *run
+  directory* (`manifest_relative_files`), so a foldered file appears as
+  `final/dialogue_short-assemble.0-0.0.mp4`.
+- The job's manifest in `jobs.sqlite`, returned by `get_job`, records files
+  relative to the *output root* (`_relative_output_names`), so the same
+  file appears as `dialogue-short/<run>/final/dialogue_short-assemble.0-0.0.mp4`.
+  `job_for_file` matches on the tail of that name, so attribution of a
+  foldered file keeps working.
+
+Both already carry directory segments, so neither needs a schema change.
+Both gain `subfolder` on each step entry so a consumer groups without
+parsing paths.
 
-```
+```text
 outputs/dialogue-short/20260911-205805-a1b2c3d4/
   manifest.json
   workflow.json
@@ -98,171 +209,221 @@ outputs/dialogue-short/20260911-205805-a1b2c3d4/
   final/dialogue_short-assemble.0-0.0.mp4
 ```
 
-The manifest already records each step's files as paths relative to the run
-directory (`manifest_relative_files`), so a foldered file appears as
-`final/dialogue_short-assemble.0-0.0.mp4` with no schema change to the
-manifest at all. Each manifest entry additionally carries `folder` (the
-empty string for an unfoldered step), so a consumer can group without
-parsing paths.
-
 ### `get_job` and `list_jobs`
 
-`get_job`'s manifest gains the `folder` on each entry, which is additive. On
-top of that, a finished job's reply carries:
-
-```json
-"outputs": { "final": ["final/...mp4"], "intermediate": ["intermediate/...mp4", "..."] }
-```
-
-- a grouping of the manifest's files by folder, so "what did this produce"
-  is answerable without walking the manifest. A job whose workflow uses no
-  folders reports `{"": [...]}`, which is the honest answer rather than a
-  guess at which file is the deliverable.
-
-`list_jobs` stays a listing: it gains nothing per job, because a row that
-carried file lists is what T018 just finished cutting down. The `total`/
-`truncated` shape is untouched.
-
-### The gallery listing (`GET /api/gallery`, MCP `list_gallery`)
-
-This is the surface where the decision above bites. The rule:
-
-- `folder` on a gallery entry stays **the workflow identity**, exactly as
-  today - `ltx2/Gyre`, not `ltx2/Gyre/final`. The folder filter continues to
-  group a workflow's runs, which is what it is for.
-- A new field, `group` (`final`, `intermediate`, or `""`), carries the
-  in-run folder, and `GET /api/gallery` takes an optional `?group=` filter
-  beside the existing `?folder=`.
-- `strip_run_id` is extended to drop everything after the run id rather than
-  just the file name: `ltx2/Gyre/<run>/final/x.mp4` -> `ltx2/Gyre`, and the
-  discarded segments become the `group`. Today's paths are unaffected
-  because they have nothing after the run id.
-
-This keeps the two axes separate - *which workflow* and *which part of the
-run* - rather than multiplying them into one filter list that grows by a
-factor of two for every workflow.
-
-### `asset:` and `previous_result:`
-
-- **`previous_result:` is unaffected.** It names a step, and results are
-  passed in memory between steps; where a step's files landed on disk has
-  never been part of it. A foldered step is read back exactly as it is now.
-- **`output:` gains one segment.** The name is
-  `<workflow identity>/<run id>/<file>`, where `<file>` is already allowed
-  to be a relative path - `_resolve_segments` walks segments and
-  `validate_output_reference` permits `/`. So
-  `output:dialogue-short/latest/final/episode.mp4` works with **no change to
-  the resolver**, and the `latest` search (newest run that holds the file)
-  keeps working because it is a per-run existence check on the whole
-  remainder of the path.
-- **`asset:` is unaffected.** The asset library is a separate tree and
-  already takes nested names (`asset:gyre/frames/web.mp4`).
-- **`keep_output`** takes the output's relative name, which now may contain
-  the folder, and writes into the asset library under `asset_name` as
-  before. The output's folder is not copied into the asset name - the two
-  trees mean different things, and a promoted file is by definition final.
+`get_job`'s manifest entries carry `subfolder`. **Nothing else is added**
+(*decided*): an earlier draft bucketed the files into an `outputs` map,
+which would have needed `""` as a JSON key for unfoldered steps and added
+a second way to read what the entries already say. The tool description
+carries the reading instead: *a step's `subfolder` says what kind of
+output it is; by convention the deliverable is `final`*.
+
+`list_jobs` stays a listing and gains nothing per job - a row that carried
+file lists is what T018 just finished cutting down.
+
+### The gallery (`GET /api/gallery`, MCP `list_gallery`)
+
+- `folder` on an entry stays **the workflow identity**, exactly as today -
+  `ltx2/Gyre`, not `ltx2/Gyre/final`. The folder filter continues to group
+  a workflow's runs, which is what it is for.
+- Each entry gains `subfolder` (`final`, `intermediate`, `""`, or whatever
+  the workflow wrote), from `split_run_path`.
+- `GET /api/gallery` takes an optional `?subfolder=` beside `?folder=`; the
+  reply's `folders` list is unchanged and gains a sibling `subfolders`
+  (distinct values over the whole tree, for the UI control).
+- MCP `list_gallery(limit, subfolder=None)`. Today it takes only `limit`,
+  so this is a new parameter, not a mirror of an existing one.
+
+The two axes - *which workflow* and *which part of the run* - stay
+separate rather than multiplying into one filter list.
+
+**Flat layout.** With `--output-layout flat` there is no run id to anchor
+on, so `subfolder` is `""` and a foldered file's directory - `ltx/final` -
+appears in the workflow filter. Accepted: flat is the legacy layout for
+callers whose scripts glob the output directory, and the on-disk placement
+is still honoured, which is what such a caller wants.
+
+### `output:`, `asset:`, `previous_result:`, `keep_output` - no change
+
+Verified against the code:
+
+- **`previous_result:`** names a step and results pass in memory; where a
+  step's files landed has never been part of it.
+- **`output:`** names are `<workflow identity>/<run id>/<file>` where
+  `<file>` is already a relative path: `_resolve_segments` walks every
+  remaining segment and `validate_output_reference` permits `/`. So
+  `output:dialogue-short/latest/final/episode.mp4` resolves with no change,
+  and `latest` (newest run *holding the file*) keeps working because it is a
+  per-run existence check on the whole remainder.
+- **`asset:`** is a separate tree that already takes nested names.
+- **`keep_output`** / `POST /api/assets/keep` take the output's relative
+  name, which may now contain the subfolder, and write into the asset
+  library under `asset_name` as before. The subfolder is not copied into
+  the asset name - a promoted file is by definition final.
+- `delete_output`, `get_output_image`, `download_output`, `/outputs/`
+  serving all take the whole remainder as a path.
 
 ### The web UI
 
-One change, mapped onto what the gallery already has: beside the existing
-folder filter (workflow identity), a second, smaller control for `group`,
-defaulting to showing everything. A run that used no folders shows exactly
-what it shows today. The job page groups the manifest it already renders
-under the same headings.
-
-The editor's form for a `result` block gains `folder` the way it gains every
-other schema field - from the schema, with no editor-specific work.
+- Gallery: a second, smaller filter for `subfolder` beside the text filter,
+  a `<select>` fed by the distinct `subfolder` values of the loaded entries
+  (the same set the server's `subfolders` lists - the page already holds
+  the whole listing and filters client-side, so no second request), shown
+  only once some output landed in one, defaulting to everything. The two
+  filters intersect. `grouping.ts` is unchanged - the server still supplies
+  `folder`.
+- Job page: the manifest it already renders is grouped under headings by
+  `subfolder` when any entry has a non-empty one - `final/` first, then in
+  order of appearance, `(run root)` for the empty value - with the step
+  headings one level down; unchanged otherwise. The grouping is live from
+  `step_end` and confirmed by the manifest (`sectionBySubfolder` in
+  `ui/src/lib/results.ts`).
+- Editor: `result.subfolder` appears from the schema, no editor work.
 
 ### Breaking changes
 
-**None over MCP or REST.** Everything above is additive: a new optional
-workflow field, new keys on existing replies, a new optional query
-parameter. Two things a scripted consumer should know:
-
-1. A manifest file name may now contain a `/` where it previously could not.
-   Anything that assumed a manifest entry was a bare file name - splitting
-   on `/` and taking the last part, or joining it to a directory by hand -
-   keeps working, but a consumer that wants the folder should read the
-   `folder` field rather than parsing the path.
-2. `gallery` entries gain `group`; `folder` keeps its current meaning. A
-   consumer filtering on `folder` sees no change.
+**None over MCP or REST, and none to existing workflows or workspaces.**
+Everything is additive: a new optional workflow field, new keys on existing
+replies, a new optional query parameter, no migration of `jobs.sqlite` or
+of run directories. Three things a consumer should know:
+
+1. A manifest file name may now contain a `/` after the run id where it
+   previously could not. A consumer that wants the subfolder should read
+   the `subfolder` field rather than parse the path.
+2. `file_base_name` containing a separator is refused at validation. It
+   failed at write time before, so no working workflow changes behaviour.
+3. **The steering stage moves template outputs.** Once a template marks
+   steps `final`/`intermediate`, its files land in `<run>/final/x.mp4`.
+   A user workflow chained off a *template's* output by run path
+   (`output:<template identity>/latest/x.mp4`) keeps resolving - `latest`
+   picks the newest run holding the file - but stops advancing past the
+   last pre-change run. `keep_output` is the supported way to make a
+   generated file a stable input. Adding `subfolder` also changes a step's
+   cache key, so the first run of a marked-up seeded template regenerates
+   rather than hitting the step cache. Both go in the release note beside
+   the `shots` list change.
+4. `$defs/result` accepts additional properties, so a workflow that already
+   carries a stray `subfolder` key validates today and is ignored; after
+   stage 1 it moves files. One line in the release note.
 
 ## Steering consumers toward it
 
-The ticket is explicit that this only pays off if the MCP consumer uses it,
-and a schema field nobody sets is worth nothing. Four places, in the order
-an agent meets them:
-
-1. **The templates.** Every multi-step template in `workflows/templates/`
-   marks its deliverable step `"folder": "final"` and its scratch steps
-   `"folder": "intermediate"`. This is the one that matters most: agents
-   compose by copying a template, so the convention propagates whether or
-   not anyone reads a description.
-2. **The authoring guide** (`docs/WORKFLOW_GUIDE.md`, the `Authoring a
-   workflow from an agent` section, and its CLAUDE.md mirror) states the
-   two-name convention and the rule: a step whose output the user will be
-   shown is `final`, everything else is `intermediate`.
-3. **Tool descriptions.** `run_workflow` says nothing new (it does not
-   author). `get_job` names the `outputs` grouping, and `save_workflow`'s
-   description states the convention for a workflow being stored for reuse.
+The ticket is explicit that this only pays off if the MCP consumer uses it.
+Four places, in the order an agent meets them:
+
+1. **The templates** (*decided*: `workflows/templates/**`, and the
+   templates the plugin skills name). A *saving step* is one whose
+   `result` sets `content_type` and does not set `save: false`; a template
+   is in scope when it has **two or more** saving steps. The deliverable
+   step gets `"subfolder": "final"`, scratch steps
+   `"subfolder": "intermediate"`; a template whose saving steps are all
+   deliverables (`image-processors`, `lora-styles` - a set of variants,
+   each final) marks them all `final`. A `workflow` step is marked
+   like any other: its `result` block saves the parent's copy of the
+   child's return value (*Sub-workflows*, above), so the role is real and
+   the child's own steps never see it. The one exemption is the packaged
+   builtins in `dw/workflows/`, which stay unmarked - a builtin is a step
+   list a parent composes, and the role is the parent's to assign
+   (*implemented*: the drift test pins both halves; the earlier draft
+   exempted `compose-workflows` and `sub-workflow`, neither of which is a
+   `builtin:` composition). One consequence: a `workflow` step's
+   deliverable exists twice - the child's copy at the run root, the
+   parent's in `final/` - so `list_gallery(subfolder="final")` shows only
+   the parent's. The duplication is older than this design; it is now
+   distinguishable. Agents compose by
+   copying a template, so the convention propagates whether or not anyone
+   reads a description. A test asserts the rule as stated here - every
+   in-scope template's saving steps all carry a subfolder - so
+   the convention cannot drift. `workflows/models/**` is out of scope for
+   this pass, though `list_workflows` returns those beside the templates;
+   marking them up is a follow-up once the convention has held in the
+   templates.
+2. **The authoring guide** (`docs/WORKFLOW_GUIDE.md`, `Authoring a workflow
+   from an agent`, and its CLAUDE.md mirror - the two change together)
+   states the rule: a step whose output the user will be shown is `final`,
+   everything else is `intermediate`.
+3. **Tool descriptions.** `get_job` states the reading; `save_workflow`
+   states the convention for a workflow stored for reuse; `list_gallery`
+   names the parameter. `run_workflow` says nothing new.
 4. **The plugin skills** (`plugins/dw/skills/*`) each state it for their
-   family's templates, which is where a composing agent is already reading.
+   family's templates.
+
+**No validation nudge** (*decided*): a warning on a multi-step workflow
+with no subfolders would fire on every existing example and on workflows
+whose outputs are all legitimately final.
 
 ## What this does not do
 
-- **No nesting policy for the libraries.** The workflow, prompt and asset
-  libraries are untouched.
-- **No automatic classification.** The engine does not guess which step is
-  final. A workflow that says nothing gets today's behaviour, and the
-  reports say `""` rather than inventing an answer.
-- **No retention policy.** "Prune the intermediates, keep the finals" is an
-  obvious next thing to want and is not part of this: it needs a decision
-  about what happens to an `output:` reference pointing into a pruned
-  folder, and that is its own proposal.
-- **No move-after-the-fact.** There is no "mark this output final" call on a
-  finished job. The folder is decided by the workflow, at write time.
-- **No change to file naming.** Names stay
-  `{workflow}-{step}.{i}-{j}.{k}.ext`; the folder is a prefix, not a
-  replacement for the step name in the name.
+- No nesting policy for the workflow, prompt or asset libraries.
+- No automatic classification: the engine does not guess which step is
+  final. A workflow that says nothing gets today's behaviour and reports
+  `""`.
+- No retention policy. "Prune the intermediates, keep the finals" is the
+  obvious next want and needs its own decision about `output:` references
+  into a pruned subfolder.
+- No move-after-the-fact: no "mark this output final" call on a finished
+  job. Placement is decided by the workflow, at write time.
+- No change to file naming.
+
+## Tests
+
+- **Engine.** An unfoldered workflow writes the same paths as today; a
+  foldered one lands in `<run>/final/`; `../final`, `/final`, `final/`,
+  `final//x`, `.hidden`, `final\x` and an absolute path are refused by
+  the shape check, a symlink escape by containment; `subfolder_errors`
+  reports the JSON path for a bad literal and for a bad `item:`-driven
+  member; a separator in `file_base_name` is refused statically and at
+  run time; a `for_each` member with an `item:` subfolder lands per
+  member; a chain step with `keep_segments` puts its segments in the
+  subfolder; `manifest.json`, the job manifest and the `step_end` event
+  all carry the `subfolder` field; a reused entry carries the definition's
+  subfolder; a parent's subfolder on a `workflow` step does not move the
+  child's files; `output:.../latest/final/x` resolves; `split_run_path`
+  on `a/b/<run>/final/x`, on a `-2` counter run id, and on a flat path.
+- **Server.** Gallery entries carry `subfolder`; `?subfolder=` filters;
+  `subfolders` lists distinct values; `job_for_file` attributes a foldered
+  file; MCP `list_gallery` passes the parameter through.
+- **UI.** Gallery subfolder filter and job-page grouping (vitest).
+- **Templates.** Every template with two or more saving steps has `final`
+  or `intermediate` on each saving step and at least one `final`; the
+  packaged builtins in `dw/workflows/` carry none.
 
 ## Phasing
 
-1. **The engine.** `folder` in the schema and in `Result.save`, path
-   validation against the run directory, `folder` on manifest entries,
-   `strip_run_id` extended. Tests: an unfoldered workflow writes exactly
-   what it writes today; a foldered one lands where it says; `../` is
-   refused; `output:.../latest/final/x.mp4` resolves.
-2. **The server surfaces.** `outputs` grouping on `get_job`, `group` on
-   gallery entries, `?group=` filter, MCP pass-through, docs.
-3. **The steering.** Templates marked up, guide and skills updated, the
-   catalog re-audited so `list_workflows` traits still hold.
-4. **The UI.** The group control on the gallery, grouped manifest on the job
-   page.
+Four stages, each its own PR to `develop`:
+
+1. **Engine.** Schema description, `subfolder_errors` in
+   `validation_errors`, `step_output_dir` feeding `Result.save` and
+   `create_step_action`, `file_base_name` check, `subfolder` on the
+   manifest entry and the `step_end` event, `split_run_path`/`strip_run_id`,
+   engine tests. `get_job` entries carry the field from this stage on -
+   the server spreads the entry as recorded.
+2. **Server and MCP.** Gallery `subfolder`/`?subfolder=`/`subfolders`,
+   MCP `list_gallery` parameter, `get_job`/`save_workflow`/`list_gallery`
+   descriptions, SERVER/MCP/GUIDE docs and the CLAUDE.md mirror.
+3. **Steering.** Templates marked up with the drift test, skills updated,
+   release note. Nothing in the catalog derivation reads `subfolder`
+   (`catalog_shape.py` reads `result.content_type` only), so shapes and
+   traits cannot move; one side effect is welcome - an `item:subfolder`
+   reference makes `subfolder` a derived entry field in a list-driven
+   workflow's `lists`.
+4. **UI.** `subfolder` on the `ManifestEntry` and `GalleryFile` types and a
+   `StepEndEvent` subtype of `JobEvent`, gallery control, job-page grouping
+   (live from `step_end`, confirmed from the manifest), editor picks the
+   field up from the schema.
 
 Stages 1 and 2 are the ticket; 3 is what makes it used; 4 is what makes it
 visible to a person rather than an agent.
 
-## Open questions
-
-1. **One level, or a path?** The ticket asks for one level deep, "to stay
-   consistent with the workflow and prompt libraries". Those libraries are
-   in fact not one level deep - both walk the tree (`workflow_names`,
-   the prompt library's `prompt:folder/name`) and a name is a relative path
-   of any depth; `templates/minimax/reference-to-video` is a real catalog
-   name with two levels. So consistency with them means *not* enforcing a
-   depth limit. My recommendation: allow a path, validate it, and make the
-   *convention* one level (`final`, `intermediate`) in the templates and the
-   guide - enforcement would be a rule with nothing behind it, and it would
-   block `shots/act-1` on a workflow that wants it. This is the one place
-   where the proposal as written diverges from the ticket, and it is Don's
-   call.
-2. **Should `get_job`'s `outputs` grouping exist at all**, or is the
-   `folder` field on each manifest entry enough? The grouping is
-   redundant-but-cheap; it exists because it answers "what did this
-   produce" in one read, which is the question the ticket is actually
-   about.
-3. **`final` as a default for a one-step workflow?** A `shot`-shape
-   workflow has exactly one output and it is the deliverable. Defaulting it
-   to `final` would make the common case right for free - but it would also
-   mean the same workflow's files move on upgrade, which breaks any stored
-   `output:` reference to them. Recommendation: no default, ever.
+## Open questions - closed
+
+1. **One level, or a path?** A path. The libraries walk the tree
+   (`templates/minimax/reference-to-video` is a real two-level catalog
+   name), so consistency with them means no depth limit; the convention is
+   one level.
+2. **`get_job` grouping?** No; the per-entry field is enough.
+3. **`final` as a default for one-step workflows?** No default, ever.
+4. **Field name?** `subfolder`, on every surface.
+5. **Steering scope?** Multi-step templates and the plugin skills'
+   templates.
+6. **Validation nudge?** No.
diff --git a/docs/superpowers/plans/2026-09-12-output-subfolders-stage-1-engine.md b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-1-engine.md
new file mode 100644
index 00000000..dbbc4867
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-1-engine.md
@@ -0,0 +1,1145 @@
+# Output Subfolders, Stage 1 (Engine) 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:** A step's `result.subfolder` places that step's files in a subfolder of the run directory, carried through the manifests and the `step_end` event, validated statically and at run time, with `strip_run_id` still grouping a workflow's runs.
+
+**Architecture:** The step's target directory is computed once in `Workflow.step_output_dir` and handed to both `Result.save` and the pipeline wrapper (so chain segment spills follow it). Shape is checked by a segment pattern aligned with `output:` references (`dw/security.py`), containment by `validate_output_path` against the run directory. A new small module `dw/subfolders.py` owns the static pass that `validation_errors` runs after `for_each` expansion, beside `previous_result_reference_errors`. `dw/runs.py` gains `split_run_path`, which finds the run-id segment anywhere in a path; `strip_run_id` becomes a wrapper over it.
+
+**Tech Stack:** Python 3, pytest. Tests run with `python -m pytest tests/<file> -q` from the repo root after `source ./activate`.
+
+**Spec:** `docs/proposals/output-folders.md` — the sections *The field*, *Where the checks live*, *`file_base_name` may no longer contain a separator*, *The engine*, *The two manifests*, *Tests* and stage 1 of *Phasing*. Stages 2-4 (server/MCP, steering, UI) are separate plans.
+
+## Global Constraints
+
+- The field is named `subfolder` everywhere: schema, manifest entries, `step_end` event.
+- No default: a step without `subfolder` writes exactly the paths it writes today.
+- Shape pattern, verbatim: `^[\w][\w.-]*(/[\w][\w.-]*)*\Z` (one or more segments; each segment starts with a word character; no `\`, no empty segment, no leading `.`/`-`).
+- The schema gets a `description` only, never a `pattern` — schema validation runs before `variable:`/`item:` substitution.
+- Filesystem access goes through `dw/security.py` validators (`validate_output_path`) — CodeQL models them as sanitizers; a bare `os.path.join` reaching the disk is a real alert.
+- `file_base_name` containing `/` or `\` is refused both statically and at run time.
+- Never use `eval()`, `exec()`, or `shell=True`.
+- Commit messages end with `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`.
+- Work on a branch off `develop` (suggested name `output-subfolders-stage-1`).
+
+---
+
+## File map
+
+| File | Responsibility in this plan |
+|---|---|
+| `dw/runs.py` | `split_run_path(relative) -> (identity, run_id, subfolder)`; `strip_run_id` wraps it |
+| `dw/security.py` | `SUBFOLDER_PATTERN`, `validate_subfolder(name)`, `validate_file_base_name(name)` |
+| `dw/subfolders.py` (new) | `SUBFOLDER_KEY`, `step_subfolder(step_definition)`, `subfolder_errors(expanded, source_indices)` |
+| `dw/workflow.py` | `validation_errors` runs `subfolder_errors`; `step_output_dir(step_definition)`; feeds `Result.save` and `create_step_action`; `subfolder` on manifest entry and `step_end` |
+| `dw/result.py` | `Result.save` refuses a separator in `file_base_name` |
+| `dw/workflow_schema.json` | `subfolder` description on `$defs/result`; `file_base_name` description amended |
+| `CLAUDE.md` | One gotcha bullet on subfolders under *Critical Gotchas* |
+| `tests/test_runs.py`, `tests/test_security.py`, `tests/test_subfolders.py` (new), `tests/test_schema.py` | Tests |
+
+---
+
+### Task 1: `split_run_path` in `dw/runs.py`
+
+**Files:**
+- Modify: `dw/runs.py:311-322` (`strip_run_id`)
+- Test: `tests/test_runs.py` (class `TestRunIds`, near line 68)
+
+**Interfaces:**
+- Produces: `split_run_path(relative_path: str) -> tuple[str, str, str]` returning `(identity, run_id, subfolder)`, each `""` when absent. `strip_run_id(relative_path) -> str` unchanged in signature and behaviour for every path it accepted before.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `tests/test_runs.py`, importing `split_run_path` alongside `strip_run_id` in the `from dw.runs import (...)` block, and inside the class that holds `test_stripping_a_run_id_gives_the_workflow_folder`:
+
+```python
+    def test_splitting_a_run_path_names_its_three_parts(self):
+        run_id = new_run_id({"id": "x"})
+        assert split_run_path(f"ltx2/Gyre/{run_id}/still.png") == (
+            "ltx2/Gyre",
+            run_id,
+            "",
+        )
+        assert split_run_path(f"ltx2/Gyre/{run_id}/final/still.png") == (
+            "ltx2/Gyre",
+            run_id,
+            "final",
+        )
+        assert split_run_path(f"ltx2/Gyre/{run_id}/shots/act-1/x.mp4") == (
+            "ltx2/Gyre",
+            run_id,
+            "shots/act-1",
+        )
+        # A counter suffix is still a run id
+        assert split_run_path(f"Gyre/{run_id}-2/final/x.mp4") == (
+            "Gyre",
+            f"{run_id}-2",
+            "final",
+        )
+
+    def test_a_path_with_no_run_id_splits_to_its_directory(self):
+        # Flat layout: nothing to anchor on, so the directory is the identity
+        assert split_run_path("ltx2/final/still.png") == ("ltx2/final", "", "")
+        assert split_run_path("still.png") == ("", "", "")
+
+    def test_stripping_a_run_id_ignores_what_follows_it(self):
+        run_id = new_run_id({"id": "x"})
+        assert strip_run_id(f"ltx2/Gyre/{run_id}/final/still.png") == "ltx2/Gyre"
+        assert strip_run_id(f"{run_id}/final/still.png") == ""
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `python -m pytest tests/test_runs.py -q -k "split_run_path or ignores_what_follows"`
+Expected: FAIL — `ImportError: cannot import name 'split_run_path'`.
+
+- [ ] **Step 3: Implement `split_run_path` and rewrite `strip_run_id` over it**
+
+Replace `strip_run_id` in `dw/runs.py` with:
+
+```python
+def split_run_path(relative_path):
+    """The three parts of a run-relative path: (identity, run id, subfolder).
+
+    'ltx2/Gyre/20260905-181530-a1b2c3d4/final/still.png' ->
+    ('ltx2/Gyre', '20260905-181530-a1b2c3d4', 'final'). The run id is
+    found wherever it sits, not only as the last directory - a step's
+    'subfolder' puts segments after it. A path with no run id in it (the
+    flat layout) has its whole directory as identity and nothing else,
+    which is what it was before subfolders existed.
+
+    Only the first segment matching RUN_ID_PATTERN counts. A workflow
+    *file* named in that shape would produce a matching identity segment;
+    that is unsupported rather than impossible.
+    """
+    parts = [part for part in (relative_path or "").split("/") if part]
+    directory = parts[:-1]
+    for position, segment in enumerate(directory):
+        if is_run_id(segment):
+            return (
+                "/".join(directory[:position]),
+                segment,
+                "/".join(directory[position + 1 :]),
+            )
+    return "/".join(directory), "", ""
+
+
+def strip_run_id(relative_path):
+    """The workflow identity a run-relative path belongs to.
+
+    'ltx2/Gyre/20260905-181530-a1b2c3d4/still-0.png' -> 'ltx2/Gyre', and
+    the same with a subfolder after the run id. A path with no run id in it
+    comes back with its own directory unchanged, which is what a
+    flat-layout output does.
+    """
+    return split_run_path(relative_path)[0]
+```
+
+- [ ] **Step 4: Run the whole runs test file**
+
+Run: `python -m pytest tests/test_runs.py -q`
+Expected: all PASS, including the pre-existing `strip_run_id` tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/runs.py tests/test_runs.py
+git commit -m "feat(runs): split_run_path finds the run id anywhere; strip_run_id wraps it
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Shape validators in `dw/security.py`
+
+**Files:**
+- Modify: `dw/security.py` (after `validate_output_reference`, around line 556)
+- Test: `tests/test_security.py`
+
+**Interfaces:**
+- Produces: `SUBFOLDER_PATTERN: str`, `MAX_SUBFOLDER_LENGTH: int = 200`, `validate_subfolder(name: str) -> str` (raises `InvalidInputError`), `validate_file_base_name(name: str) -> str` (raises `InvalidInputError` on `/` or `\`).
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_security.py` (match its existing import style — it imports from `dw.security`):
+
+```python
+class TestSubfolderValidation:
+    def test_a_segment_path_is_accepted(self):
+        from dw.security import validate_subfolder
+
+        assert validate_subfolder("final") == "final"
+        assert validate_subfolder("shots/act-1") == "shots/act-1"
+        assert validate_subfolder("a.b_c-d/e") == "a.b_c-d/e"
+
+    @pytest.mark.parametrize(
+        "bad",
+        [
+            "",
+            "../final",
+            "final/..",
+            "/final",
+            "final/",
+            "final//x",
+            ".hidden",
+            "-dash",
+            "final\\x",
+            "final x",
+            "fin:al",
+        ],
+    )
+    def test_the_shape_refuses_what_output_references_refuse(self, bad):
+        from dw.security import InvalidInputError, validate_subfolder
+
+        with pytest.raises(InvalidInputError):
+            validate_subfolder(bad)
+
+    def test_too_long_is_refused(self):
+        from dw.security import InvalidInputError, validate_subfolder
+
+        with pytest.raises(InvalidInputError):
+            validate_subfolder("a" * 201)
+
+
+class TestFileBaseNameValidation:
+    def test_a_plain_name_is_accepted(self):
+        from dw.security import validate_file_base_name
+
+        assert validate_file_base_name("episode_") == "episode_"
+
+    @pytest.mark.parametrize("bad", ["final/", "a/b", "a\\b"])
+    def test_a_separator_is_refused_and_names_subfolder(self, bad):
+        from dw.security import InvalidInputError, validate_file_base_name
+
+        with pytest.raises(InvalidInputError, match="subfolder"):
+            validate_file_base_name(bad)
+```
+
+Add `import pytest` at the top of the file if it is not already imported.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `python -m pytest tests/test_security.py -q -k "Subfolder or FileBaseName"`
+Expected: FAIL — `ImportError: cannot import name 'validate_subfolder'`.
+
+- [ ] **Step 3: Implement the validators**
+
+Insert after `validate_output_reference` in `dw/security.py`:
+
+```python
+# A step's result 'subfolder': a relative path under the run directory. The
+# segment rule is OUTPUT_REFERENCE_PATTERN's, so every subfolder the engine
+# writes is one a later workflow can name with 'output:'. It also refuses a
+# backslash, which DANGEROUS_PATTERNS does not - '"final\\x"' would be one
+# directory on POSIX and two on Windows
+SUBFOLDER_PATTERN = r"^[\w][\w.-]*(/[\w][\w.-]*)*\Z"
+MAX_SUBFOLDER_LENGTH = 200
+
+
+def validate_subfolder(name: str) -> str:
+    """
+    Validate the shape of a result 'subfolder'.
+
+    Containment is checked separately, by the validate_output_path call
+    that joins it onto the run directory.
+
+    Args:
+        name: The subfolder as written in the workflow
+
+    Returns:
+        The validated name
+
+    Raises:
+        InvalidInputError: If the name is not a valid subfolder
+    """
+    return _validate_name(
+        name,
+        SUBFOLDER_PATTERN,
+        MAX_SUBFOLDER_LENGTH,
+        "Subfolder",
+        "a subfolder is one or more path segments under the run directory, "
+        "each starting with a letter, digit or underscore, like 'final' or "
+        "'shots/act-1'",
+    )
+
+
+def validate_file_base_name(name: str) -> str:
+    """
+    Validate a result 'file_base_name': a name, never a path.
+
+    A separator here used to pass validation and then fail at open() because
+    the directory did not exist. Placement is what 'subfolder' is for.
+
+    Raises:
+        InvalidInputError: If the name carries a path separator
+    """
+    if "/" in name or "\\" in name:
+        raise InvalidInputError(
+            f"Invalid file_base_name: {name} - a file_base_name is a name, not "
+            f"a path; to write into a subfolder of the run directory set "
+            f"'subfolder' on the result instead"
+        )
+    return name
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `python -m pytest tests/test_security.py -q`
+Expected: all PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/security.py tests/test_security.py
+git commit -m "feat(security): validate_subfolder and validate_file_base_name
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: `dw/subfolders.py` — the static pass, wired into `validation_errors`
+
+**Files:**
+- Create: `dw/subfolders.py`
+- Modify: `dw/workflow.py:351-382` (`validation_errors`), imports near line 35-75
+- Test: `tests/test_subfolders.py` (new)
+
+**Interfaces:**
+- Consumes: `validate_subfolder`, `validate_file_base_name` from Task 2; `render_path`, `MEMBER_SEPARATOR` from `dw/for_each.py`.
+- Produces: `SUBFOLDER_KEY = "subfolder"`; `step_subfolder(step_definition: dict) -> str` (validated value, or `""` when absent; raises `InvalidInputError` on a bad one); `subfolder_errors(workflow_definition: dict, source_indices: list[int] | None = None) -> list[dict]` with `{path, message}` entries in the same shape `previous_result_reference_errors` returns.
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `tests/test_subfolders.py`:
+
+```python
+import pytest
+
+from dw.security import InvalidInputError
+from dw.subfolders import step_subfolder, subfolder_errors
+
+
+def _step(name, result=None, **extra):
+    step = {"name": name, "task": {"command": "noop", "arguments": {}}}
+    if result is not None:
+        step["result"] = result
+    step.update(extra)
+    return step
+
+
+class TestStepSubfolder:
+    def test_absent_is_the_empty_string(self):
+        assert step_subfolder(_step("a")) == ""
+        assert step_subfolder(_step("a", {"content_type": "image/png"})) == ""
+
+    def test_present_is_returned_validated(self):
+        assert step_subfolder(_step("a", {"subfolder": "final"})) == "final"
+
+    def test_a_bad_one_raises(self):
+        with pytest.raises(InvalidInputError):
+            step_subfolder(_step("a", {"subfolder": "../x"}))
+
+    def test_a_non_string_raises(self):
+        with pytest.raises(InvalidInputError):
+            step_subfolder(_step("a", {"subfolder": 3}))
+
+
+class TestSubfolderErrors:
+    def test_a_clean_definition_has_none(self):
+        definition = {
+            "steps": [
+                _step("a", {"content_type": "image/png", "subfolder": "final"}),
+                _step("b", {"content_type": "image/png"}),
+            ]
+        }
+        assert subfolder_errors(definition) == []
+
+    def test_a_bad_subfolder_is_reported_at_its_path(self):
+        definition = {"steps": [_step("a", {"subfolder": "../escape"})]}
+        errors = subfolder_errors(definition)
+        assert len(errors) == 1
+        assert errors[0]["path"] == "steps[0].result.subfolder"
+        assert "Subfolder" in errors[0]["message"] or "subfolder" in errors[0]["message"]
+
+    def test_a_separator_in_file_base_name_is_reported_at_its_path(self):
+        definition = {"steps": [_step("a", {"file_base_name": "final/"})]}
+        errors = subfolder_errors(definition)
+        assert [e["path"] for e in errors] == ["steps[0].result.file_base_name"]
+        assert "subfolder" in errors[0]["message"]
+
+    def test_an_expanded_member_reports_the_source_step_and_names_the_member(self):
+        # expand_for_each turned steps[1] into two members; the author wrote
+        # one step, so the path is the source's and the member is named
+        definition = {
+            "steps": [
+                _step("intro", {"subfolder": "final"}),
+                _step("shot@a", {"subfolder": "ok"}),
+                _step("shot@b", {"subfolder": "bad/../x"}),
+            ]
+        }
+        errors = subfolder_errors(definition, source_indices=[0, 1, 1])
+        assert len(errors) == 1
+        assert errors[0]["path"] == "steps[1].result.subfolder"
+        assert "shot@b" in errors[0]["message"]
+
+    def test_an_unsubstituted_reference_is_left_alone(self):
+        # A 'variable:' still spelled out is one nothing resolved; that is
+        # the undeclared-variable pass's complaint, not this one's
+        definition = {"steps": [_step("a", {"subfolder": "variable:dest"})]}
+        assert subfolder_errors(definition) == []
+
+    def test_no_steps_is_fine(self):
+        assert subfolder_errors({}) == []
+        assert subfolder_errors({"steps": "nope"}) == []
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `python -m pytest tests/test_subfolders.py -q`
+Expected: FAIL — `ModuleNotFoundError: No module named 'dw.subfolders'`.
+
+- [ ] **Step 3: Create the module**
+
+Create `dw/subfolders.py`:
+
+```python
+"""A step's result 'subfolder': where under the run directory its files go.
+
+A run writes everything into one directory, so a finished episode sits
+beside the twenty scratch files that went into it, distinguished only by
+the step name in each file name. 'subfolder' on a step's result block puts
+that step's files into a subfolder of the run directory instead - by
+convention 'final' or 'intermediate', though the engine treats no name
+specially. Nothing else about placement changes: a step without one writes
+where it always did.
+
+This module owns the shape check and the static pass over an expanded
+definition. Containment - that the joined path really is inside the run
+directory - is the engine's, at the moment it joins (see
+Workflow.step_output_dir).
+"""
+
+from .for_each import MEMBER_SEPARATOR, render_path
+from .security import (
+    InvalidInputError,
+    validate_file_base_name,
+    validate_subfolder,
+)
+
+SUBFOLDER_KEY = "subfolder"
+FILE_BASE_NAME_KEY = "file_base_name"
+
+# Reference prefixes substitution resolves before this pass runs. One still
+# spelled out here is one nothing resolved, and that is the undeclared-
+# variable pass's complaint rather than a shape error
+_UNRESOLVED_PREFIXES = ("variable:", "item:")
+
+
+def step_subfolder(step_definition):
+    """The validated subfolder a step's result names, or '' when it names
+    none.
+
+    Raises:
+        InvalidInputError: If the value is not a string or not a valid
+            subfolder
+    """
+    result = step_definition.get("result")
+    if not isinstance(result, dict) or SUBFOLDER_KEY not in result:
+        return ""
+    value = result[SUBFOLDER_KEY]
+    if not isinstance(value, str):
+        raise InvalidInputError(
+            f"Invalid subfolder: {value!r} - a subfolder is a string like 'final'"
+        )
+    return validate_subfolder(value)
+
+
+def subfolder_errors(workflow_definition, source_indices=None):
+    """Every result 'subfolder' or 'file_base_name' that cannot be written,
+    as [{path, message}].
+
+    The definition handed here has already been substituted and expanded,
+    so every value in it is literal; a 'variable:' or 'item:' still spelled
+    out is left alone. `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")
+        if not isinstance(result, dict):
+            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 ""
+        )
+        for key, check in (
+            (SUBFOLDER_KEY, validate_subfolder),
+            (FILE_BASE_NAME_KEY, validate_file_base_name),
+        ):
+            if key not in result:
+                continue
+            value = result[key]
+            if isinstance(value, str) and value.startswith(_UNRESOLVED_PREFIXES):
+                continue
+            try:
+                if not isinstance(value, str):
+                    raise InvalidInputError(
+                        f"Invalid {key}: {value!r} - expected a string"
+                    )
+                check(value)
+            except InvalidInputError as e:
+                errors.append(
+                    {
+                        "path": render_path(("steps", source, "result", key)),
+                        "message": f"{e}{where}",
+                    }
+                )
+    return errors
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `python -m pytest tests/test_subfolders.py -q`
+Expected: all PASS.
+
+- [ ] **Step 5: Write the failing integration test for `validation_errors`**
+
+Append to `tests/test_subfolders.py`:
+
+```python
+class TestValidationErrorsIntegration:
+    def _workflow(self, definition, tmp_path):
+        from dw.workflow import Workflow
+
+        return Workflow(definition, str(tmp_path), "/w/workflows/Sub.json")
+
+    def test_validation_errors_reports_a_bad_subfolder(self, tmp_path):
+        definition = {
+            "id": "sub_test",
+            "steps": [
+                {
+                    "name": "a",
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {"content_type": "image/png", "subfolder": "../x"},
+                }
+            ],
+        }
+        errors = self._workflow(definition, tmp_path).validation_errors()
+        assert [e["path"] for e in errors] == ["steps[0].result.subfolder"]
+
+    def test_a_variable_driven_subfolder_is_checked_by_its_value(self, tmp_path):
+        definition = {
+            "id": "sub_test",
+            "variables": {"dest": "final"},
+            "steps": [
+                {
+                    "name": "a",
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {"content_type": "image/png", "subfolder": "variable:dest"},
+                }
+            ],
+        }
+        workflow = self._workflow(definition, tmp_path)
+        assert workflow.validation_errors() == []
+        errors = workflow.validation_errors(arguments={"dest": "../x"})
+        assert [e["path"] for e in errors] == ["steps[0].result.subfolder"]
+
+    def test_an_item_driven_subfolder_is_checked_per_member(self, tmp_path):
+        definition = {
+            "id": "sub_test",
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": [
+                        {"name": "a", "dest": "shots/a"},
+                        {"name": "b", "dest": "../x"},
+                    ],
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {"content_type": "image/png", "subfolder": "item:dest"},
+                }
+            ],
+        }
+        errors = self._workflow(definition, tmp_path).validation_errors()
+        assert len(errors) == 1
+        assert errors[0]["path"] == "steps[0].result.subfolder"
+        assert "shot@b" in errors[0]["message"]
+```
+
+Run: `python -m pytest tests/test_subfolders.py -q -k Integration`
+Expected: FAIL — `validation_errors()` returns `[]` for the bad subfolder (the schema accepts any string and nothing checks it yet). `noop` is fine as a command: the schema types `task.command` as a free-form string, and these tests only validate, never run.
+
+- [ ] **Step 6: Wire `subfolder_errors` into `validation_errors`**
+
+In `dw/workflow.py`, add the import beside the `previous_result_reference_errors` import (find it with `grep -n previous_result_reference_errors dw/workflow.py`):
+
+```python
+from .subfolders import step_subfolder, subfolder_errors
+```
+
+Change the last line of `validation_errors` from:
+
+```python
+        return previous_result_reference_errors(expanded, source_indices)
+```
+
+to:
+
+```python
+        return previous_result_reference_errors(
+            expanded, source_indices
+        ) + subfolder_errors(expanded, source_indices)
+```
+
+- [ ] **Step 7: Run the tests to verify they pass**
+
+Run: `python -m pytest tests/test_subfolders.py tests/test_previous_results.py tests/test_for_each.py -q`
+Expected: all PASS (`step_subfolder` is imported now and used in Task 5; an unused import here is fine for one commit).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add dw/subfolders.py dw/workflow.py tests/test_subfolders.py
+git commit -m "feat(validate): subfolder_errors checks result.subfolder and file_base_name after expansion
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Schema descriptions
+
+**Files:**
+- Modify: `dw/workflow_schema.json` (`$defs/result`, around line 1099-1115)
+- Test: `tests/test_schema.py`
+
+**Interfaces:**
+- Produces: `$defs/result.properties.subfolder` (`type: string`, description only).
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_schema.py` (check its imports; it already imports `load_schema` or `validate_data_all` from `dw.schema` — use whichever it has, or add `from dw.schema import load_schema, validate_data_all`):
+
+```python
+class TestResultSubfolder:
+    def test_subfolder_is_a_described_string_with_no_pattern(self):
+        result = load_schema("workflow")["$defs"]["result"]["properties"]
+        assert result["subfolder"]["type"] == "string"
+        assert "final" in result["subfolder"]["description"]
+        # Schema validation runs before substitution, so a pattern would
+        # reject 'variable:dest' and 'item:subfolder'
+        assert "pattern" not in result["subfolder"]
+
+    def test_a_workflow_with_a_subfolder_validates(self):
+        definition = {
+            "id": "s",
+            "steps": [
+                {
+                    "name": "a",
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {"content_type": "image/png", "subfolder": "variable:dest"},
+                }
+            ],
+        }
+        assert validate_data_all(definition, load_schema("workflow")) == []
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `python -m pytest tests/test_schema.py -q -k Subfolder`
+Expected: FAIL — `KeyError: 'subfolder'`.
+
+- [ ] **Step 3: Add the property and amend `file_base_name`**
+
+In `dw/workflow_schema.json`, inside `$defs.result.properties`, change the `file_base_name` description and add `subfolder` after it:
+
+```json
+                "file_base_name": {
+                    "description": "The base name for saving result and metadata files. A name, not a path - it may not contain a separator; to place a step's files in a subfolder of the run directory set 'subfolder'. The file extension is determined by context and content_type.",
+                    "type": "string"
+                },
+                "subfolder": {
+                    "description": "A subfolder of the run directory this step's files are written into, as a relative path like 'final' or 'shots/act-1'. Optional: without it the files land at the root of the run directory as they always have. By convention a step whose output the user will be shown is 'final' and everything else is 'intermediate', which is how a consumer tells the deliverable from the scratch files without knowing the workflow; the engine treats no name specially. May be a 'variable:' or, inside a for_each step, an 'item:' reference. Each segment must start with a letter, digit or underscore; '..' and '\\' are refused.",
+                    "type": "string"
+                },
+```
+
+- [ ] **Step 4: Run the schema tests**
+
+Run: `python -m pytest tests/test_schema.py tests/test_configuration_schema.py -q`
+Expected: all PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/workflow_schema.json tests/test_schema.py
+git commit -m "feat(schema): result.subfolder, description only; file_base_name is a name not a path
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: `Workflow.step_output_dir` feeds `Result.save` and the pipeline wrapper
+
+**Files:**
+- Modify: `dw/workflow.py` — new method beside `effective_output_dir` (line ~285); the `result.save(...)` call at ~743; the three `output_dir=self.effective_output_dir` kwargs in `create_step_action` at ~962, ~1003, ~1032
+- Modify: `dw/result.py:305-313` (`file_base_name` handling in `Result.save`)
+- Test: `tests/test_runs.py`
+
+**Interfaces:**
+- Consumes: `step_subfolder` (Task 3), `validate_output_path` (already imported in `workflow.py`), `validate_file_base_name` (Task 2).
+- Produces: `Workflow.step_output_dir(step_definition: dict) -> str` — the absolute directory this step writes into, created; equals `self.effective_output_dir` when the step has no subfolder. Raises `InvalidInputError` / `PathTraversalError` on a bad or escaping subfolder.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `tests/test_runs.py` a helper beside `_workflow_definition()`:
+
+```python
+def _foldered_definition(subfolder="final"):
+    definition = _workflow_definition()
+    definition["steps"][0]["result"]["subfolder"] = subfolder
+    return definition
+```
+
+and a new class:
+
+```python
+class TestSubfolders:
+    def test_a_step_without_a_subfolder_writes_where_it_always_did(
+        self, tmp_path, fake_pipeline
+    ):
+        from dw.workflow import Workflow
+
+        Workflow(_workflow_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "runs_test-gen0.0-0.0.png").is_file()
+        assert not any(child.is_dir() for child in run.iterdir())
+
+    def test_a_step_with_a_subfolder_writes_into_it(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "final" / "runs_test-gen0.0-0.0.png").is_file()
+        assert not (run / "runs_test-gen0.0-0.0.png").exists()
+        # The manifest still sits at the root of the run
+        assert (run / "manifest.json").is_file()
+
+    def test_a_nested_subfolder_is_created(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(
+            _foldered_definition("shots/act-1"), str(tmp_path), "/w/workflows/Gyre.json"
+        ).run({})
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "shots" / "act-1" / "runs_test-gen0.0-0.0.png").is_file()
+
+    def test_step_output_dir_is_the_run_directory_without_a_subfolder(self, tmp_path):
+        from dw.workflow import Workflow
+
+        workflow = Workflow(_workflow_definition(), str(tmp_path), "/w/workflows/Gyre.json")
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        step = workflow.workflow_definition["steps"][0]
+        assert workflow.step_output_dir(step) == workflow.effective_output_dir
+
+    def test_step_output_dir_refuses_an_escape_at_run_time(self, tmp_path):
+        from dw.security import SecurityError
+        from dw.workflow import Workflow
+
+        workflow = Workflow(
+            _foldered_definition("../other"), str(tmp_path), "/w/workflows/Gyre.json"
+        )
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        with pytest.raises(SecurityError):
+            workflow.step_output_dir(workflow.workflow_definition["steps"][0])
+
+    def test_the_pipeline_wrapper_is_pointed_at_the_subfolder(self, tmp_path, fake_pipeline):
+        # A chain step's save_segments spill writes through the pipeline's
+        # output_dir, so it has to be the step's directory, not the run's
+        from dw.workflow import Workflow
+
+        workflow = Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json")
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        step = workflow.workflow_definition["steps"][0]
+        action = workflow.create_step_action(step, {}, {}, 7, "cpu")
+        assert action.output_dir == os.path.join(workflow.effective_output_dir, "final")
+
+    def test_a_separator_in_file_base_name_is_refused_at_save(self, tmp_path):
+        from dw.result import Result
+        from dw.security import InvalidInputError
+
+        result = Result({"content_type": "image/png", "file_base_name": "final/"})
+        with pytest.raises(InvalidInputError, match="subfolder"):
+            result.save(str(tmp_path), "w-step.0")
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `python -m pytest tests/test_runs.py -q -k TestSubfolders`
+Expected: the "writes where it always did" test PASSES (that is the regression guard); every other test FAILS (`AttributeError: 'Workflow' object has no attribute 'step_output_dir'`, files landing at the root, `InvalidInputError` not raised).
+
+- [ ] **Step 3: Add `step_output_dir`**
+
+In `dw/workflow.py`, directly after the `effective_output_dir` property:
+
+```python
+    def step_output_dir(self, step_definition):
+        """Where one step writes: the run directory, or the subfolder of it
+        the step's result names.
+
+        Computed here, once, rather than inside Result.save, because two
+        things write on a step's behalf - Result.save for its results and
+        the pipeline wrapper for a chain's save_segments spill - and both
+        have to land in the same place. The shape was checked statically by
+        validation_errors; it is checked again here for a definition that
+        reached the engine without it, and containment (that the joined
+        path is really inside the run directory) is checked on the join.
+        """
+        base = self.effective_output_dir
+        subfolder = step_subfolder(step_definition)
+        if not subfolder:
+            return base
+        target = validate_output_path(os.path.join(base, subfolder), base)
+        os.makedirs(target, exist_ok=True)
+        return target
+```
+
+Confirm `os` is imported in `dw/workflow.py` (it is used by `effective_output_dir`).
+
+- [ ] **Step 4: Feed it to `Result.save` and to the pipeline wrappers**
+
+In the step loop (~line 743), change:
+
+```python
+                    saved_files = result.save(
+                        self.effective_output_dir, f"{workflow_id}-{step.name}.{i}"
+                    )
+```
+
+to:
+
+```python
+                    saved_files = result.save(
+                        self.step_output_dir(step_data),
+                        f"{workflow_id}-{step.name}.{i}",
+                    )
+```
+
+In `create_step_action`, replace each of the three `output_dir=self.effective_output_dir,` kwargs (the cached-pipeline reuse branch ~962, the fresh `Pipeline(...)` ~1003, and the `pipeline_reference` branch ~1032) with:
+
+```python
+                    output_dir=self.step_output_dir(step_definition),
+```
+
+(`step_definition` is the parameter name in `create_step_action`; keep each line's existing indentation.) Do not touch the `workflow` (sub-workflow) branch: a child's steps compute their own directories against the inherited run directory, and the parent's `subfolder` governs only what the parent saves from the child's return value — which the `result.save` change above already covers.
+
+- [ ] **Step 5: Refuse a separator in `file_base_name` at save time**
+
+In `dw/result.py`, change the import line to include the new validator:
+
+```python
+from .security import (
+    SecurityError,
+    validate_file_base_name,
+    validate_output_path,
+    validate_string_input,
+)
+```
+
+and in `Result.save`, change:
+
+```python
+        if "file_base_name" in self.result_definition:
+            custom_base = validate_string_input(
+                self.result_definition["file_base_name"],
+                max_length=MAX_BASE_NAME_LENGTH,
+            )
+            file_base_name = custom_base + validated_base_name
+```
+
+to:
+
+```python
+        if "file_base_name" in self.result_definition:
+            custom_base = validate_file_base_name(
+                validate_string_input(
+                    self.result_definition["file_base_name"],
+                    max_length=MAX_BASE_NAME_LENGTH,
+                )
+            )
+            file_base_name = custom_base + validated_base_name
+```
+
+Note the check happens before the `save`/`content_type` early return? It does not need to — the early return is above; a `file_base_name` on a step that saves nothing is harmless. Leave the order as it is (early return first, then base name).
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `python -m pytest tests/test_runs.py tests/test_result.py tests/test_result_output_naming.py tests/test_chain.py tests/test_step_cache.py -q`
+Expected: all PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add dw/workflow.py dw/result.py tests/test_runs.py
+git commit -m "feat(engine): result.subfolder places a step's files; step_output_dir feeds Result.save and the pipeline wrapper
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: `subfolder` on the manifest entry and the `step_end` event
+
+**Files:**
+- Modify: `dw/workflow.py` — manifest entry assembly (~line 761) and `step_end_data` (~769)
+- Test: `tests/test_runs.py`
+
+**Interfaces:**
+- Consumes: `step_subfolder` (Task 3).
+- Produces: every manifest step entry carries `"subfolder": str` (`""` when none); every `step_end` event carries `subfolder=str`. Stage 2 and the UI read these.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `TestSubfolders` in `tests/test_runs.py`:
+
+```python
+    def test_the_manifest_entry_carries_the_subfolder(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        manifest = json.loads((run / "manifest.json").read_text())
+        (entry,) = manifest["steps"]
+        assert entry["subfolder"] == "final"
+        assert entry["files"] == ["final/runs_test-gen0.0-0.0.png"]
+
+    def test_an_unfoldered_entry_carries_the_empty_string(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(_workflow_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        manifest = json.loads((run / "manifest.json").read_text())
+        assert manifest["steps"][0]["subfolder"] == ""
+
+    def test_a_reused_entry_carries_the_definitions_subfolder(
+        self, tmp_path, fake_pipeline
+    ):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        first, second = sorted((tmp_path / "Gyre").iterdir())
+        manifest = json.loads((second / "manifest.json").read_text())
+        (entry,) = manifest["steps"]
+        assert entry["reused"] is True
+        assert entry["subfolder"] == "final"
+        # The file is the first run's, absolute, inside its 'final'
+        assert os.path.dirname(entry["files"][0]) == str(first / "final")
+
+    def test_the_step_end_event_carries_the_subfolder(self, tmp_path, fake_pipeline):
+        from dw.events import RunContext
+        from dw.workflow import Workflow
+
+        seen = []
+        context = RunContext(on_event=seen.append)
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}, previous_pipelines={}, context=context
+        )
+        step_ends = [event for event in seen if event.get("event") == "step_end"]
+        assert step_ends and step_ends[0]["subfolder"] == "final"
+```
+
+(`RunContext(on_event=...)` and `run(..., context=context)` is the same setup `tests/test_events.py::_run` uses.)
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `python -m pytest tests/test_runs.py -q -k "carries or step_end_event"`
+Expected: FAIL — `KeyError: 'subfolder'`.
+
+- [ ] **Step 3: Add the field in both places**
+
+In the step loop of `dw/workflow.py`, change:
+
+```python
+                manifest_entry = {"step": step.name, "files": saved_files}
+                if reused:
+                    manifest_entry["reused"] = True
+```
+
+to:
+
+```python
+                subfolder = step_subfolder(step_data)
+                manifest_entry = {
+                    "step": step.name,
+                    "files": saved_files,
+                    "subfolder": subfolder,
+                }
+                if reused:
+                    manifest_entry["reused"] = True
+```
+
+and:
+
+```python
+                step_end_data = {"files": saved_files}
+                if reused:
+                    step_end_data["reused"] = True
+```
+
+to:
+
+```python
+                step_end_data = {"files": saved_files, "subfolder": subfolder}
+                if reused:
+                    step_end_data["reused"] = True
+```
+
+- [ ] **Step 4: Run the tests to verify they pass, then the wider set**
+
+Run: `python -m pytest tests/test_runs.py -q`
+Expected: all PASS.
+
+Run: `python -m pytest tests/ -q -x --ignore=tests/test_plugin_skills.py`
+Expected: all PASS. If a server or MCP test asserts the exact key set of a manifest entry or a `step_end` payload, update that assertion to include `subfolder` — that is the field arriving, not a regression. Note which test needed it in the commit message.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/workflow.py tests/test_runs.py
+git commit -m "feat(engine): manifest entries and step_end carry subfolder
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: `output:` reaches into a subfolder — the no-change claim, pinned by a test
+
+**Files:**
+- Test: `tests/test_runs.py`
+
+**Interfaces:**
+- Consumes: `resolve_output_reference` (`dw/runs.py`, unchanged).
+
+- [ ] **Step 1: Write the test**
+
+Add to `TestSubfolders` in `tests/test_runs.py` (import `resolve_output_reference` from `dw.runs` in the file's import block if it is not already there):
+
+```python
+    def test_an_output_reference_reaches_into_a_subfolder(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        resolved = resolve_output_reference(
+            "output:Gyre/latest/final/runs_test-gen0.0-0.0.png", root=str(tmp_path)
+        )
+        assert resolved == str(run / "final" / "runs_test-gen0.0-0.0.png")
+        assert resolve_output_reference(
+            f"output:Gyre/{run.name}/final/runs_test-gen0.0-0.0.png", root=str(tmp_path)
+        ) == resolved
+```
+
+- [ ] **Step 2: Run it**
+
+Run: `python -m pytest tests/test_runs.py -q -k reaches_into`
+Expected: PASS on the first run — the resolver already walks every remaining segment. If it fails, stop: the design's no-change claim about `_resolve_segments` is wrong and needs a look before anything else, not a patch here.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_runs.py
+git commit -m "test(runs): output: references reach a step's subfolder unchanged
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: CLAUDE.md gotcha and the design's status line
+
+**Files:**
+- Modify: `CLAUDE.md` (*Critical Gotchas*, after the *Run directories* bullet)
+- Modify: `docs/proposals/output-folders.md:3` (status)
+
+- [ ] **Step 1: Add the gotcha**
+
+After the `**Run directories**` bullet in `CLAUDE.md`'s *Critical Gotchas*, add:
+
+```markdown
+- **Result subfolders**: a step's `result.subfolder` (`dw/subfolders.py`) puts its files
+  in a subfolder of the run directory - `<run>/final/x.mp4` - by convention `final` or
+  `intermediate`; the engine treats no name specially and there is no default.
+  `Workflow.step_output_dir` computes the directory once and hands it to both
+  `Result.save` and the pipeline wrapper, so a chain's `save_segments` spill follows it.
+  Shape is `SUBFOLDER_PATTERN` (the `output:` segment rule, so every subfolder is
+  `output:`-addressable), checked by `subfolder_errors` in `validation_errors` after
+  `for_each` expansion and again at run time; containment is `validate_output_path`
+  against the run directory. Manifest entries and `step_end` carry `subfolder`.
+  `split_run_path` finds the run id anywhere in a path, so `strip_run_id` still groups a
+  workflow's runs. `file_base_name` may not contain a separator - it is a name, not a path
+```
+
+- [ ] **Step 2: Update the design's status**
+
+Change line 3 of `docs/proposals/output-folders.md` to:
+
+```markdown
+Status: **stage 1 (engine) implemented; stages 2-4 pending**. Written for MCP feedback ticket T016;
+```
+
+- [ ] **Step 3: Run the full suite once**
+
+Run: `python -m pytest tests/ -q --ignore=tests/test_plugin_skills.py`
+Expected: all PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add CLAUDE.md docs/proposals/output-folders.md
+git commit -m "docs: result subfolders gotcha; output-folders design marks stage 1 done
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review
+
+**Spec coverage (stage 1 items):** schema description → Task 4; `subfolder_errors` in `validation_errors` → Task 3; `step_output_dir` feeding `Result.save` and `create_step_action` → Task 5; `file_base_name` check, static and run time → Tasks 2, 3, 5; `subfolder` on manifest entry and `step_end` → Task 6; `split_run_path`/`strip_run_id` → Task 1; engine tests listed in the spec's *Tests* section — unfoldered identical (5), foldered lands (5), shape refusals (2), symlink/escape containment (5, `refuses_an_escape_at_run_time`), `subfolder_errors` path for literal and `item:` member (3), `file_base_name` static and run time (3, 5), `for_each` member per subfolder (3 covers validation; a run-level `item:` placement test is not included because the `noop` task fixture cannot save — the substitution path is the one `_rewrite` already walks, verified in the design review), chain `keep_segments` follows the subfolder (5, via the wrapper's `output_dir`), reused entry (6), parent's subfolder does not move a child's files (not tested — no code path changed for sub-workflows; the design states the semantics), `output:` resolves (7), `split_run_path` cases (1). `get_job` carrying the field needs no code (the server spreads `**entry`).
+
+**Placeholders:** none; every step has its code. The `noop` task command and the `RunContext(on_event=...)` capture were checked against the schema and `tests/test_events.py` while writing.
+
+**Type consistency:** `step_subfolder(step_definition) -> str`, `subfolder_errors(definition, source_indices) -> list[dict]`, `validate_subfolder(name) -> str`, `validate_file_base_name(name) -> str`, `split_run_path(path) -> (str, str, str)`, `Workflow.step_output_dir(step_definition) -> str` — used with these names and shapes in every task that references them.
diff --git a/docs/superpowers/plans/2026-09-12-output-subfolders-stage-2-server.md b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-2-server.md
new file mode 100644
index 00000000..262cd470
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-2-server.md
@@ -0,0 +1,600 @@
+# Output Subfolders, Stage 2 (Server + MCP) 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:** A caller can see, over REST and MCP, which subfolder each output sits in — on gallery entries, as a gallery filter, and in the tool and guide text that tells an agent what the field means.
+
+**Architecture:** The engine already writes subfolders and records them on manifest entries and `step_end` events (stage 1, merged as `685f594`). Stage 2 changes no write path. The gallery walker in `dw/server/app.py` splits a path with `split_run_path` instead of `strip_run_id`, so each entry carries `subfolder` beside `folder` (which keeps meaning workflow identity); `GET /api/gallery` takes `?subfolder=` and answers `subfolders`. MCP `list_gallery` grows the one parameter. Docs and tool descriptions carry the `final`/`intermediate` convention. Two engine tests the stage-1 review left unpinned are added.
+
+**Tech Stack:** Python 3, FastAPI, pytest. Tests: `source ./activate` then `python -m pytest tests/<file> -q`.
+
+**Spec:** `docs/proposals/output-folders.md` — sections *The gallery*, *`get_job` and `list_jobs`*, *`output:`, `asset:` … no change*, *Breaking changes*, and stage 2 of *Phasing*. The design is the authority; this plan argues from it.
+
+## Global Constraints
+
+- The field is `subfolder` everywhere: gallery entry key, query parameter, reply list (`subfolders`), MCP parameter.
+- On a gallery entry `folder` keeps its meaning — the workflow identity (`ltx2/Gyre`), never `ltx2/Gyre/final`.
+- `subfolder` is `""` for a file with nothing after its run id, and for every flat-layout file (no run id to anchor on) — documented, not special-cased.
+- `get_job` gains no new key: manifest entries already carry `subfolder` (the server spreads the entry). Only its description changes.
+- `list_jobs` is untouched.
+- No engine write-path change. The two new engine tests pin existing behaviour.
+- `docs/WORKFLOW_GUIDE.md`'s *Authoring a workflow from an agent* and its CLAUDE.md mirror (the *Type System* bullet list) change together.
+- Commit messages end with `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`.
+- Branch off `develop` (suggested `output-subfolders-stage-2`).
+
+---
+
+## File map
+
+| File | Responsibility in this plan |
+|---|---|
+| `dw/server/app.py` | `_iter_gallery_files` yields `subfolder`; `_gallery_entries` carries it; `GET /api/gallery` filters on it and lists `subfolders` |
+| `dw_mcp/catalog.py` | `list_gallery(client, limit=50, subfolder=None)` |
+| `dw_mcp/server.py` | `list_gallery` signature + docstring; `get_job`, `save_workflow`, `validate_workflow` docstrings |
+| `docs/SERVER.md`, `docs/MCP.md`, `docs/WORKFLOW_GUIDE.md`, `CLAUDE.md` | The field, the convention, the filter |
+| `tests/test_server.py`, `tests/test_jobs_reused.py`, `tests/test_mcp_catalog.py`, `tests/test_runs.py` | Tests |
+
+---
+
+### Task 1: Gallery entries carry `subfolder`; `?subfolder=` and `subfolders`
+
+**Files:**
+- Modify: `dw/server/app.py` — `_iter_gallery_files` (~line 1952), `_gallery_entries` (~1978), the `/api/gallery` route (~2018), and the asset-library caller of `_iter_gallery_files` (~2334, `group_runs=False`); the import line `from ..runs import is_output_reference, resolve_output_reference, strip_run_id` (~67)
+- Test: `tests/test_server.py`
+
+**Interfaces:**
+- Consumes: `split_run_path(relative) -> (identity, run_id, subfolder)` from `dw/runs.py` (stage 1).
+- Produces: `_iter_gallery_files(root, group_runs=True)` yields `(relative_name, folder, subfolder, kind, path)`; gallery entries carry `"subfolder": str`; `GET /api/gallery?subfolder=<s>` filters; the reply carries `"subfolders": [sorted distinct values]`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_server.py`, after `test_gallery_paginates_and_groups_by_workflow_folder`:
+
+```python
+def test_gallery_reports_and_filters_by_subfolder(server, tmp_path):
+    """A step's `result.subfolder` puts its files under
+    '<identity>/<run id>/<subfolder>/'. The gallery keeps `folder` meaning
+    the workflow identity - a workflow run fifty times is still one folder
+    - and carries the in-run subfolder as its own axis, so 'which workflow'
+    and 'which part of the run' never multiply into one filter list."""
+    from PIL import Image
+
+    from dw.runs import new_run_id
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        run_id = new_run_id({"id": "dialogue"})
+        run = outputs / "dialogue" / run_id
+        (run / "final").mkdir(parents=True)
+        (run / "intermediate" / "shots").mkdir(parents=True)
+        Image.new("RGB", (2, 2)).save(run / "final" / "dialogue-assemble.0-0.0.png")
+        Image.new("RGB", (2, 2)).save(run / "intermediate" / "dialogue-shot.0-0.0.png")
+        Image.new("RGB", (2, 2)).save(
+            run / "intermediate" / "shots" / "dialogue-slice.0-0.0.png"
+        )
+        Image.new("RGB", (2, 2)).save(run / "dialogue-still.0-0.0.png")
+        # a flat-layout file: no run id, so nothing to hang a subfolder on
+        (outputs / "ltx").mkdir()
+        Image.new("RGB", (2, 2)).save(outputs / "ltx" / "flat.png")
+
+        full = client.get("/api/gallery").json()
+        by_name = {f["name"]: f for f in full["files"]}
+
+        # folder is the identity, subfolder is what followed the run id
+        final = by_name[f"dialogue/{run_id}/final/dialogue-assemble.0-0.0.png"]
+        assert final["folder"] == "dialogue"
+        assert final["subfolder"] == "final"
+        nested = by_name[f"dialogue/{run_id}/intermediate/shots/dialogue-slice.0-0.0.png"]
+        assert nested["subfolder"] == "intermediate/shots"
+        assert by_name[f"dialogue/{run_id}/dialogue-still.0-0.0.png"]["subfolder"] == ""
+        assert by_name["ltx/flat.png"]["folder"] == "ltx"
+        assert by_name["ltx/flat.png"]["subfolder"] == ""
+
+        # the two axes stay separate
+        assert set(full["folders"]) == {"", "dialogue", "ltx"}
+        assert full["subfolders"] == ["", "final", "intermediate", "intermediate/shots"]
+
+        # the filter narrows listing and total; combined with folder it intersects
+        finals = client.get("/api/gallery?subfolder=final").json()
+        assert finals["total"] == 1
+        assert finals["files"][0]["subfolder"] == "final"
+        both = client.get("/api/gallery?folder=dialogue&subfolder=").json()
+        assert {f["name"] for f in both["files"]} == {
+            f"dialogue/{run_id}/dialogue-still.0-0.0.png"
+        }
+        # subfolders is over the whole tree, not the filtered page
+        assert finals["subfolders"] == full["subfolders"]
+```
+
+Also append to `tests/test_jobs_reused.py` (the design lists attribution of a foldered file as a server test; it is expected to PASS already — `_manifest_wrote` matches on the tail — and pins that):
+
+```python
+def test_job_for_file_attributes_a_file_in_a_subfolder(tmp_path):
+    # A step's result.subfolder puts a segment between the run id and the
+    # file; the recorded name and the gallery's name both carry it
+    history = JobHistory(str(tmp_path / "jobs.sqlite"))
+    name = "dialogue/20260912-120000-abcdef01/final/dialogue-assemble.0-0.0.png"
+
+    _record(history, "writer", 1.0, [{"step": "assemble", "files": [name], "subfolder": "final"}])
+
+    assert history.job_for_file(name)["id"] == "writer"
+```
+
+- [ ] **Step 2: Run the tests to verify the state**
+
+Run: `python -m pytest tests/test_server.py -q -k reports_and_filters_by_subfolder` — Expected: FAIL, `KeyError: 'subfolder'`.
+Run: `python -m pytest tests/test_jobs_reused.py -q` — Expected: PASS (pinning test; if it fails, stop and report rather than patching `jobs.py`).
+
+- [ ] **Step 3: Implement**
+
+In `dw/server/app.py`, change the runs import to:
+
+```python
+from ..runs import is_output_reference, resolve_output_reference, split_run_path
+```
+
+(`strip_run_id` has no other use in this file once the walker changes — check with `grep -n strip_run_id dw/server/app.py`; if another use exists, keep both names.)
+
+Rewrite `_iter_gallery_files`:
+
+```python
+    def _iter_gallery_files(root, group_runs=True):
+        """Every media file under a directory tree. Yields (relative_name,
+        folder, subfolder, kind, path) - relative_name always uses '/' so
+        it round-trips through a URL the same way on every platform.
+
+        With group_runs (the gallery's own use, over the output directory):
+        recurses into the per-workflow subfolders (dw/workflow.py's
+        effective_output_dir writes each run under '<workflow
+        identity>/<run id>/', and mirrors a workflow's position under a
+        'workflows' tree in the flat layout). The folder a file is grouped
+        under is the identity - the run id is dropped, so a workflow run
+        fifty times is one folder in the filter, not fifty - and whatever
+        followed the run id is the subfolder, the part of the run a step's
+        'result.subfolder' put it in ('final', 'intermediate'). A flat-layout
+        path has no run id to anchor on, so its subfolder is '' and its
+        whole directory is the folder, as it always was.
+
+        Without it (the asset library's use, which has no run ids to strip):
+        folder is just the plain relative directory and subfolder is ''."""
+        for current, _dirs, names in os.walk(root):
+            rel_root = os.path.relpath(current, root)
+            directory = "" if rel_root == "." else rel_root.replace(os.sep, "/")
+            for name in names:
+                extension = os.path.splitext(name)[1].lower()
+                kind = MEDIA_KINDS.get(extension)
+                if kind is None:
+                    continue
+                relative_name = name if not directory else f"{directory}/{name}"
+                if group_runs:
+                    folder, _run_id, subfolder = split_run_path(relative_name)
+                else:
+                    folder, subfolder = directory, ""
+                yield relative_name, folder, subfolder, kind, os.path.join(current, name)
+```
+
+In `_gallery_entries`, unpack five and add the key:
+
+```python
+        for relative_name, folder, subfolder, kind, path in files:
+            ...
+            entries.append(
+                {
+                    "name": relative_name,
+                    "folder": folder,
+                    "subfolder": subfolder,
+                    ...
+```
+
+At the asset-library caller (~2334), unpack five as well: `for relative_name, folder, _subfolder, kind, path in files:` (match whatever names that loop uses).
+
+Change the route:
+
+```python
+    @app.get("/api/gallery")
+    def gallery(
+        limit: int = 200,
+        offset: int = 0,
+        folder: Optional[str] = None,
+        subfolder: Optional[str] = None,
+        ws: Workspace = Depends(selected_workspace),
+    ):
+        """A page of media files in the output directory, newest first.
+        Stateless by design - the gallery survives server restarts because
+        it reads the directory tree, not job history. 'folders' lists every
+        distinct workflow folder present (over the whole directory, not just
+        this page), for the UI's folder filter - a run id is not a folder of
+        its own, so a workflow's runs group together; '' stands for files
+        saved directly at the output root, and is itself always a member so
+        that folder-less outputs stay selectable once anything is nested.
+        'subfolders' is the other axis, over the whole directory the same
+        way: the in-run subfolders steps wrote into ('final',
+        'intermediate'), '' for files at a run's root. `folder` and
+        `subfolder` filter independently and intersect when both are given."""
+        entries = _gallery_entries(ws.outputs, ws)
+        folders = sorted({e["folder"] for e in entries} | {""})
+        subfolders = sorted({e["subfolder"] for e in entries} | {""})
+        if folder is not None:
+            entries = [e for e in entries if e["folder"] == folder]
+        if subfolder is not None:
+            entries = [e for e in entries if e["subfolder"] == subfolder]
+        offset = max(0, offset)
+        limit = max(0, limit)
+        page = entries[offset : offset + limit]
+        return {
+            "files": page,
+            "total": len(entries),
+            "offset": offset,
+            "limit": limit,
+            "folders": folders,
+            "subfolders": subfolders,
+            "workspace": ws.name,
+        }
+```
+
+- [ ] **Step 4: Run the server tests**
+
+Run: `python -m pytest tests/test_server.py tests/test_server_workspaces.py -q`
+Expected: all PASS. If a test asserts the exact key set of a gallery entry or reply, add `subfolder` / `subfolders` to that assertion and name the test in the commit body.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py tests/test_jobs_reused.py
+git commit -m "feat(server): gallery entries carry subfolder; ?subfolder= filter and subfolders list
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: MCP `list_gallery(subfolder=)` and the tool descriptions
+
+**Files:**
+- Modify: `dw_mcp/catalog.py:140-142`, `dw_mcp/server.py` (`list_gallery` ~300, `validate_workflow` ~547, `save_workflow` ~577, `get_job` ~696)
+- Test: `tests/test_mcp_catalog.py`
+
+**Interfaces:**
+- Consumes: `GET /api/gallery?subfolder=` (Task 1).
+- Produces: `catalog.list_gallery(client, limit=50, subfolder=None) -> dict` — sends `subfolder` only when it is not `None` (an empty string IS sent: it means "files at a run's root"); MCP tool `list_gallery(limit: int = 50, subfolder: str | None = None)`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `tests/test_mcp_catalog.py` after `test_list_gallery_sends_its_limit`:
+
+```python
+def test_list_gallery_sends_a_subfolder_only_when_given():
+    client, seen = recording_client()
+    catalog.list_gallery(client, limit=7)
+    assert "subfolder" not in seen["params"]
+
+    client, seen = recording_client()
+    catalog.list_gallery(client, subfolder="final")
+    assert seen["params"]["subfolder"] == "final"
+
+    # '' is a real filter - files at a run's root - not "no filter"
+    client, seen = recording_client()
+    catalog.list_gallery(client, subfolder="")
+    assert seen["params"]["subfolder"] == ""
+```
+
+Check how `recording_client` records params (read its definition at the top of the file); if it stringifies values, `""` stays `""`.
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `python -m pytest tests/test_mcp_catalog.py -q -k subfolder`
+Expected: FAIL — `TypeError: list_gallery() got an unexpected keyword argument 'subfolder'`.
+
+- [ ] **Step 3: Implement the catalog function**
+
+```python
+def list_gallery(client, limit=50, subfolder=None):
+    """Generated media in the output directory, newest first. `subfolder`
+    narrows to one in-run subfolder ('final', 'intermediate', '' for files
+    at a run's root); None means every file."""
+    params = {"limit": limit}
+    if subfolder is not None:
+        params["subfolder"] = subfolder
+    return client.get_json("/api/gallery", params=params)
+```
+
+- [ ] **Step 4: Update the MCP tool and the three descriptions**
+
+In `dw_mcp/server.py`, `list_gallery`:
+
+```python
+    def list_gallery(limit: int = 50, subfolder: str | None = None) -> dict:
+        """List generated output files, newest first. A name is
+        <workflow>/<run id>/<file>, where <file> may itself sit in a
+        subfolder the step chose (`final/episode.mp4`) - the form
+        `get_output_image`, `get_output_text`, `download_output`,
+        `keep_output` and `delete_output` all take, and the form an
+        "output:" reference in a later workflow is built from. Each entry
+        carries `folder` (the workflow) and `subfolder` (the part of the run:
+        by convention `final` is the deliverable and `intermediate` the
+        scratch work, '' when the step chose none); `subfolder=` filters on
+        the latter, so `subfolder="final"` is "what did these runs
+        deliver". Each entry also carries a ready-made `url` for viewing the
+        file over HTTP, already scoped to the right workspace; use it as
+        given rather than composing one from the name."""
+        return catalog.list_gallery(client, limit=limit, subfolder=subfolder)
+```
+
+`get_job` — replace the docstring with:
+
+```python
+        """Get a job's status, argument warnings, output manifest, error and
+        traceback. The manifest names each step's files the way
+        `get_output_image`, `download_output` and `keep_output` take them,
+        and each entry's `subfolder` says what kind of output the step
+        declared - by convention `final` is the deliverable, `intermediate`
+        the scratch work, and '' a step that said nothing. A step served
+        from the step cache is marked `reused` and reports the earlier run's
+        files. When a job failed, the error and traceback here are what to
+        read before changing anything."""
+```
+
+`save_workflow` — append one sentence to its docstring, before the closing quotes:
+
+```
+        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.
+```
+
+`validate_workflow` — append one sentence:
+
+```
+        A `result.subfolder` or `file_base_name` that cannot be written (a
+        `..`, a backslash, a separator in `file_base_name`) is reported here
+        at its JSON path, after `for_each` expansion.
+```
+
+- [ ] **Step 5: Run the MCP tests**
+
+Run: `python -m pytest tests/test_mcp_catalog.py tests/test_mcp_server.py tests/test_mcp_media.py tests/test_server_mcp.py -q`
+Expected: all PASS. `tests/test_mcp_server.py` lists tool names and may snapshot signatures — if it asserts `list_gallery`'s parameters, add `subfolder` there and name the test in the commit body.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dw_mcp/catalog.py dw_mcp/server.py tests/test_mcp_catalog.py
+git commit -m "feat(mcp): list_gallery(subfolder=); get_job/save_workflow/validate_workflow state the subfolder convention
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Docs — SERVER, MCP, WORKFLOW_GUIDE and the CLAUDE.md mirror
+
+**Files:**
+- Modify: `docs/SERVER.md` (the `GET /api/gallery` bullet ~297; the `GET /api/jobs/{id}` row ~141; the `step_start`/`step_end` row ~165), `docs/MCP.md` (the `list_gallery` row ~229; the `get_job` row ~286), `docs/WORKFLOW_GUIDE.md` (*Authoring a workflow from an agent* — new `###` subsection before `### Being found next time` ~515; *Result Configuration* ~533), `CLAUDE.md` (*Type System* bullet list)
+
+No code, so no TDD; the check is that the text agrees with the code as landed and that the two mirrors move together.
+
+- [ ] **Step 1: `docs/SERVER.md`**
+
+Extend the `GET /api/gallery` bullet (~297) so it reads:
+
+```markdown
+- `GET /api/gallery`, `GET /api/gallery/{name}/metadata`,
+  `DELETE /api/gallery/{name}` — outputs and their embedded metadata. Each
+  gallery entry carries `folder` (the workflow identity, the run id dropped)
+  and `subfolder` (what followed the run id - the `final`/`intermediate` a
+  step's `result.subfolder` chose, `''` when it chose none); `?folder=` and
+  `?subfolder=` filter independently, and the reply's `folders` and
+  `subfolders` list every distinct value over the whole tree, `''` always a
+  member of each so root-level files stay selectable
+```
+
+In the `GET /api/jobs/{id}` row (~141), after "carries `reused: true`.", insert: "Every entry carries `subfolder` - the in-run subfolder the step's `result.subfolder` chose, `''` for none."
+
+In the `step_start` / `step_end` row (~165), change "`files` at the end" to "`files` and `subfolder` at the end".
+
+- [ ] **Step 2: `docs/MCP.md`**
+
+Replace the `list_gallery` row (~229) with:
+
+```markdown
+| `list_gallery(limit=50, subfolder=None)` | `limit`, `subfolder` | 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` (`final`, `intermediate`, or `''`), 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 |
+```
+
+In the `get_job` row (~286), after "output manifest," insert "(each entry's `subfolder` says whether the step declared its output `final`, `intermediate`, or nothing)".
+
+- [ ] **Step 3: `docs/WORKFLOW_GUIDE.md`**
+
+Insert before `### Being found next time` (in *Authoring a workflow from an agent*). The block below is fenced with four backticks because it contains a three-backtick fence of its own:
+
+````markdown
+### Saying which output is the deliverable
+
+A run writes everything into one directory, so a finished episode sits
+beside the twenty scratch files that went into it. A step's `result` block
+can name a subfolder of the run directory for its files:
+
+```json
+"result": { "content_type": "video/mp4", "subfolder": "final" }
+```
+
+The convention is two names: `final` for a step whose output the user will
+be shown, `intermediate` for everything else. The engine treats no name
+specially and applies no default - a step that says nothing writes to the
+run's root as it always has - but the gallery, `get_job` and `list_gallery`
+all carry the value, so a consumer that follows the convention can tell the
+deliverable from the scratch without knowing the workflow. Mark every saving
+step of a multi-step workflow; a one-step workflow needs nothing.
+
+The value is a relative path of any depth (`shots/act-1`), may be a
+`variable:` or, inside a `for_each` step, an `item:` reference, and follows
+the `output:` segment rule - each segment starts with a letter, digit or
+underscore; `..`, a backslash and a leading `.` are refused - so every
+subfolder written is one a later workflow can name:
+`output:dialogue-short/latest/final/episode.mp4`. A bad value is a
+validation error at its JSON path. `file_base_name` is a name, not a path:
+a separator there is refused, and `subfolder` is the way to place a file.
+````
+
+In *Result Configuration* (~533), change the JSON example to:
+
+```json
+"result": {
+    "content_type": "image/jpeg",
+    "save": true,
+    "file_base_name": "custom_prefix",
+    "subfolder": "final"
+}
+```
+
+and add after the content-types paragraph: "`subfolder` places the step's files in a subfolder of the run directory - see *Saying which output is the deliverable* above. `file_base_name` may not contain a path separator."
+
+- [ ] **Step 4: `CLAUDE.md` mirror**
+
+Stage 1 already wrote a `**Result subfolders**` bullet under *Critical Gotchas* holding the mechanics (`dw/subfolders.py`, `step_output_dir`, `SUBFOLDER_PATTERN`, containment, manifest/`step_end`). Do not repeat those. Two edits:
+
+(a) In the *Type System* bullet list (the one beginning "`arguments.py` + `type_helpers.py` handle dynamic type conversion"), add a bullet after the `prompt:` bullet carrying the *convention* only:
+
+```markdown
+- A step's `result.subfolder` names a subfolder of the run directory for that step's
+  files - by convention `final` for the deliverable and `intermediate` for the rest; any
+  relative path (`shots/act-1`); `variable:`/`item:` allowed; no default. Mechanics under
+  *Result subfolders* in Critical Gotchas
+```
+
+(b) In the existing `**Result subfolders**` gotcha, change its last sentence "`file_base_name` may not contain a separator - it is a name, not a path" to:
+
+```markdown
+  Gallery entries carry it too; `GET /api/gallery?subfolder=` and MCP
+  `list_gallery(subfolder=)` filter on it. `file_base_name` may not contain a separator -
+  it is a name, not a path
+```
+
+- [ ] **Step 5: Check the guides still load and the suite is green**
+
+Run: `python -m pytest tests/test_mcp_guides.py tests/test_docs.py -q 2>/dev/null || python -m pytest tests/test_mcp_guides.py -q`
+Then: `python -m pytest tests/ -q --ignore=tests/test_plugin_skills.py`
+Expected: all PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add docs/SERVER.md docs/MCP.md docs/WORKFLOW_GUIDE.md CLAUDE.md
+git commit -m "docs: subfolder on gallery entries, list_gallery filter, the final/intermediate convention in the authoring guide and its CLAUDE.md mirror
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Two engine tests the stage-1 review left unpinned
+
+**Files:**
+- Test: `tests/test_runs.py` (class `TestSubfolders`)
+
+No engine change. Both tests pin behaviour that is correct by inspection; if either fails, stop and report — do not patch the engine.
+
+- [ ] **Step 1: Write the tests**
+
+Add to `TestSubfolders`:
+
+```python
+    def test_a_parents_subfolder_does_not_move_a_childs_files(
+        self, tmp_path, fake_pipeline
+    ):
+        # A 'workflow' step's own result block governs what the parent saves
+        # from the child's return value; the child's steps place their own
+        # files, into the run directory they inherit
+        from dw.workflow import Workflow
+
+        tree = tmp_path / "workflows"
+        tree.mkdir()
+        (tree / "child.json").write_text(json.dumps(_workflow_definition()))
+        parent = {
+            "id": "parent",
+            "seed": 7,
+            "steps": [
+                {
+                    "name": "child",
+                    "workflow": {"path": "child.json"},
+                    "result": {"subfolder": "final"},
+                }
+            ],
+        }
+        Workflow(parent, str(tmp_path / "out"), str(tree / "Parent.json")).run({})
+        (run,) = (tmp_path / "out" / "Parent").iterdir()
+        assert (run / "runs_test-gen0.0-0.0.png").is_file()
+        assert not (run / "final" / "runs_test-gen0.0-0.0.png").exists()
+
+    def test_a_chain_spill_lands_in_the_steps_subfolder(self, tmp_path, fake_pipeline):
+        # save_segments writes through the pipeline wrapper's output_dir,
+        # which create_step_action points at the step's subfolder
+        from dw.pipeline_processors.chain import run_chain
+        from dw.workflow import Workflow
+        from tests.test_chain import FakePipeline, video_output
+
+        workflow = Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json")
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        action = workflow.create_step_action(
+            workflow.workflow_definition["steps"][0], {}, {}, 7, "cpu"
+        )
+        spilling = FakePipeline(
+            video_output, output_dir=action.output_dir, file_prefix=action.file_prefix
+        )
+        run_chain(
+            spilling,
+            {"segments": 2, "trim_frames": 1, "fps": 4, "save_segments": True,
+             "keep_segments": True},
+            {},
+        )
+        segments = sorted((tmp_path / "Gyre" / "run" / "final").glob("*.segment-*.mp4"))
+        assert len(segments) == 2
+```
+
+Before running, check: (a) that `Workflow` resolves a sub-workflow's `path` relative to the parent's `file_spec` directory (read the `workflow` branch of `create_step_action`); if it needs the parent file to exist, write `parent` to `tree / "Parent.json"` and load it with `workflow_from_file`; (b) the exact child file name — the child's id is `runs_test`, its step `gen0` — and adjust the asserted name to what the run wrote if the workflow-step naming differs, keeping the assertion that it is at the run root and not under `final/`; (c) that `tests/test_chain.py` exports `FakePipeline` and `video_output` at module level and `FakePipeline` accepts `output_dir`/`file_prefix` kwargs (it does in `TestSaveSegments.make_pipeline`); (d) the attribute name the `Pipeline` wrapper stores its file prefix under (`file_prefix` per the constructor kwarg — confirm in `dw/pipeline_processors/pipeline.py`).
+
+- [ ] **Step 2: Run**
+
+Run: `python -m pytest tests/test_runs.py -q`
+Expected: all PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_runs.py
+git commit -m "test(runs): a parent's subfolder leaves a child's files alone; a chain spill lands in the step's subfolder
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Design status
+
+**Files:**
+- Modify: `docs/proposals/output-folders.md:3`
+
+- [ ] **Step 1: Update the status line** to:
+
+```markdown
+Status: **stages 1-2 (engine, server/MCP) implemented; stages 3-4 pending**. Written for MCP feedback ticket T016;
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/proposals/output-folders.md
+git commit -m "docs: output-folders design marks stage 2 done
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review
+
+**Spec coverage (stage 2 phasing):** gallery `subfolder`/`?subfolder=`/`subfolders` → Task 1; MCP `list_gallery` parameter → Task 2; `get_job`/`save_workflow`/`list_gallery` descriptions → Task 2 (plus `validate_workflow` — an addition beyond the design's list, because *Where the checks live* makes it the surface that reports a bad value); SERVER/MCP/GUIDE docs and the CLAUDE.md mirror → Task 3; the design's *Tests* items for the server → Task 1 (entries, filter, list, `job_for_file` attribution of a foldered file); stage-1 deferred tests → Task 4. Not in scope: the UI (`GalleryFile` type, filter control, job-page grouping — stage 4), templates and skills (stage 3), the `step_subfolder` double evaluation (Fable: harmless; left).
+
+**Placeholders:** none. Task 4 names four things to confirm before running and says what to keep constant.
+
+**Type consistency:** `split_run_path -> (identity, run_id, subfolder)`; `_iter_gallery_files` five-tuple `(relative_name, folder, subfolder, kind, path)` in both callers; `catalog.list_gallery(client, limit=50, subfolder=None)` matches `server.list_gallery(limit=50, subfolder=None)`.
diff --git a/docs/superpowers/plans/2026-09-12-output-subfolders-stage-3-steering.md b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-3-steering.md
new file mode 100644
index 00000000..42c8796b
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-3-steering.md
@@ -0,0 +1,495 @@
+# Output Subfolders, Stage 3 (Steering) 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:** Every shipped multi-step template says which of its outputs is the deliverable, a test keeps that from drifting, the plugin skills state the convention for their families, and the docs carry the release note.
+
+**Architecture:** No engine or server code changes. Stage 3 is data and prose: `"subfolder": "final"` / `"subfolder": "intermediate"` added to the `result` block of every saving step in every `workflows/templates/**` file that has two or more saving steps; a new `tests/test_template_subfolders.py` asserts the rule so it cannot drift and pins the packaged builtins in `dw/workflows/` as unmarked; one sentence in each of the three plugin skills (`plugins/dw/skills/*/SKILL.md`) with a test in `tests/test_plugin_skills.py`; the authoring guide, `CLAUDE.md` and the design doc updated.
+
+**Tech Stack:** JSON, Markdown, pytest. Tests: `source ./activate` then `python -m pytest tests/<file> -q`.
+
+**Spec:** `docs/proposals/output-folders.md` — sections *Steering consumers toward it*, *Breaking changes* (item 3), *Tests* (the *Templates* bullet), and stage 3 of *Phasing*. The design is the authority; this plan argues from it. One ruling against its text is recorded under Global Constraints.
+
+## Global Constraints
+
+- A **saving step** is a step whose `result` sets `content_type` and does not set `"save": false`. A template is **in scope** when it has two or more saving steps. Definition copied from the design's *Steering* item 1.
+- Every saving step of an in-scope template carries a literal `"subfolder"` of exactly `"final"` or `"intermediate"`; every in-scope template has at least one `final` step. No `variable:`/`item:` subfolders in templates - the roles are fixed by the template's shape.
+- **Ruling (deviation from the design text):** the design exempts "a template whose saving steps are all `workflow` steps over `builtin:` children (`compose-workflows`, `sub-workflow`)". Neither named template is over a builtin (`compose-workflows` takes the child paths as variables; `sub-workflow` names `./lora.json` and has a `task` step too), and a `workflow` step's own `result` block saves a real file - the parent's copy of the child's return value, written through `Result.save(self.step_output_dir(step_data), ...)` in `dw/workflow.py` - which the design's own *Sub-workflows* paragraph states. The exemption therefore protects nothing: the child's steps never see the parent's subfolder. **Both templates are marked like any other.** The one exemption that survives is the packaged builtins in `dw/workflows/` themselves, which stay unmarked and are pinned so by the drift test. The design's *Steering* paragraph is corrected in Task 4. Cost if wrong: two templates' parent-saved files land in `final/`/`intermediate/` where the design said root - a one-line revert per file.
+- `workflows/models/**` is out of scope (design, *decided*). The drift test walks `workflows/templates/**` only.
+- The `subfolder` key goes **last** in the `result` object, after every existing key, so the diff is one added line per step and the templates read alike.
+- Only the `result` blocks change in the templates: no re-indenting, no key reordering, no description edits. Files are 2-space-indented JSON; keep it.
+- `docs/WORKFLOW_GUIDE.md`'s *Authoring a workflow from an agent* section and its CLAUDE.md mirror change together (CLAUDE.md rule).
+- Commit messages end with `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`.
+- Branch off `develop` (suggested `output-subfolders-stage-3`).
+
+---
+
+## File map
+
+| File | Responsibility in this plan |
+|---|---|
+| `tests/test_template_subfolders.py` (new) | The drift test: every in-scope template's saving steps all carry `final`/`intermediate`, at least one `final`; builtins unmarked |
+| `workflows/templates/**/*.json` (18 files, listed in Task 1) | Gain `"subfolder"` on each saving step's `result` |
+| `plugins/dw/skills/minimax-h3/SKILL.md`, `.../ltx-2.5/SKILL.md`, `.../minimax-music3/SKILL.md` | One paragraph each stating the convention for the family's templates |
+| `tests/test_plugin_skills.py` | Pins that each skill states the convention and that the H3 skill's named roles match the templates |
+| `docs/WORKFLOW_GUIDE.md` | *Saying which output is the deliverable*: says the shipped templates follow the convention |
+| `CLAUDE.md` | *Result subfolders* gotcha: the templates are marked; the release-note line |
+| `docs/proposals/output-folders.md` | Status → stages 1-3 done; *Steering* item 1 corrected per the ruling |
+
+---
+
+### Task 1: Drift test and template markup
+
+**Files:**
+- Create: `tests/test_template_subfolders.py`
+- Modify: the 18 templates in the table below (only their `result` blocks)
+
+**Interfaces:**
+- Consumes: `get_example_files()` from `tests/test_examples.py` (returns repo-relative paths of every workflow JSON under `workflows/`, sorted); `REPO_ROOT` from the same module.
+- Produces: `saving_steps(definition)` and `IN_SCOPE` (list of repo-relative template paths) in the new test module - Task 2's test imports neither; it reads the templates directly.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_template_subfolders.py`:
+
+```python
+"""Every multi-step template says which of its outputs is the deliverable.
+
+A run writes everything into one directory, so a finished episode sits
+beside the scratch that went into it. A step's `result.subfolder` places
+its files - by convention `final` for the deliverable and `intermediate`
+for the rest (docs/WORKFLOW_GUIDE.md, "Saying which output is the
+deliverable"). Agents compose by copying a template, so the convention
+propagates only if every shipped template follows it; this test is what
+keeps it from drifting.
+
+The rule, from docs/proposals/output-folders.md: a *saving step* is one
+whose `result` sets `content_type` and does not set `save: false`; a
+template is in scope when it has two or more saving steps; every saving
+step of an in-scope template carries `final` or `intermediate`, and at
+least one is `final`. The packaged builtins in dw/workflows/ stay unmarked:
+a builtin is a step list a parent composes, and a role is the parent's to
+assign - the parent's own `result` block, not the child's, is where it
+says so.
+"""
+
+import json
+import os
+
+import pytest
+
+from tests.test_examples import BUILTIN_DIR, REPO_ROOT, get_example_files
+
+CONVENTION = {"final", "intermediate"}
+
+
+def load(relative_path):
+    with open(os.path.join(REPO_ROOT, relative_path), encoding="utf-8") as file:
+        return json.load(file)
+
+
+def saving_steps(definition):
+    """The steps whose result is written to disk."""
+    for step in definition.get("steps", []):
+        result = step.get("result") or {}
+        if result.get("content_type") and result.get("save", True) is not False:
+            yield step
+
+
+TEMPLATES = [f for f in get_example_files() if f.startswith("workflows/templates/")]
+IN_SCOPE = [f for f in TEMPLATES if len(list(saving_steps(load(f)))) >= 2]
+
+
+def test_the_scope_is_what_the_design_counted():
+    """Eighteen templates had two or more saving steps when the convention
+    landed. A template added later with several saving steps joins the
+    parametrized test below on its own; this pins that none has quietly
+    left it (a step that stopped saving would drop a template from scope
+    without failing anything else)."""
+    assert len(IN_SCOPE) >= 18, IN_SCOPE
+
+
+@pytest.mark.parametrize("template", IN_SCOPE)
+def test_every_saving_step_of_a_multi_step_template_names_its_role(template):
+    steps = list(saving_steps(load(template)))
+    roles = {step["name"]: step["result"].get("subfolder") for step in steps}
+
+    unmarked = sorted(name for name, role in roles.items() if role not in CONVENTION)
+    assert not unmarked, (
+        f"{template}: saving steps without a final/intermediate subfolder: {unmarked}"
+    )
+    assert "final" in roles.values(), f"{template}: no step is marked final"
+
+
+@pytest.mark.parametrize("template", IN_SCOPE)
+def test_the_subfolder_is_the_last_key_of_the_result(template):
+    """One added line per step, and every template reads alike."""
+    for step in saving_steps(load(template)):
+        assert list(step["result"])[-1] == "subfolder", (
+            f"{template}: step {step['name']!r} does not end its result with subfolder"
+        )
+
+
+@pytest.mark.parametrize(
+    "builtin", sorted(name for name in os.listdir(BUILTIN_DIR) if name.endswith(".json"))
+)
+def test_the_packaged_builtins_stay_unmarked(builtin):
+    with open(os.path.join(BUILTIN_DIR, builtin), encoding="utf-8") as file:
+        definition = json.load(file)
+    marked = [
+        step["name"]
+        for step in definition.get("steps", [])
+        if "subfolder" in (step.get("result") or {})
+    ]
+    assert not marked, f"dw/workflows/{builtin} marks {marked}; a role is the parent's to assign"
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `source ./activate && python -m pytest tests/test_template_subfolders.py -q`
+Expected: the 18 `test_every_saving_step_of_a_multi_step_template_names_its_role` cases FAIL with "saving steps without a final/intermediate subfolder"; the 18 last-key cases FAIL; scope and builtin cases PASS. If `test_the_scope_is_what_the_design_counted` fails, stop and report - the inventory below is wrong.
+
+- [ ] **Step 3: Mark up the templates**
+
+For each row, add `"subfolder": "<role>"` as the **last** key of that step's `result` object (after `embed_metadata`, `file_base_name`, whatever is there), with a comma on the previous last line. Nothing else in the file changes.
+
+| Template (`workflows/templates/`) | Step | Role | Why |
+|---|---|---|---|
+| `compose-workflows.json` | `image_generation` | `intermediate` | the still the video is conditioned on |
+| | `video_generation` | `final` | |
+| `consistent-set.json` | `base` | `intermediate` | the subject picture the three edits start from |
+| | `first`, `second`, `third` | `final` | the set |
+| `controlnet.json` | `canny` | `intermediate` | control image |
+| | `FluxCanny` | `final` | |
+| `describe-and-regenerate.json` | `describe_image` | `intermediate` | text |
+| | `augment_prompt` | `intermediate` | text |
+| | `flux` | `final` | |
+| `image-processors.json` | all 25 saving steps | `final` | a set of variants, each a deliverable |
+| `lora-styles.json` | all 10 saving steps | `final` | a set of variants, each a deliverable |
+| `recenter-crop.json` | `frame_1`, `frame_2`, `frame_3` | `final` | the registered stills are the output |
+| `qr-code.json` | `qr_code` | `intermediate` | |
+| | `init_image` | `intermediate` | |
+| | `main` | `final` | |
+| `restore-faces.json` | `generate` | `intermediate` | |
+| | `restore` | `final` | |
+| `segment-and-inpaint.json` | `segment` | `intermediate` | mask |
+| | `inpaint` | `final` | |
+| `sub-workflow.json` | `logo` | `intermediate` | the parent's copy of the child's return |
+| | `remove_background` | `final` | |
+| `ltx2/generative-upscale.json` | `low_resolution` | `intermediate` | |
+| | `upscaled` | `final` | |
+| `minimax/dialogue-short.json` | `draw_character_a`, `draw_character_b` | `intermediate` | portraits |
+| | `shot` (the `for_each` step - one `result` block) | `intermediate` | the cuts |
+| | `episode` | `final` | |
+| `minimax/enhance-prompt.json` | `prompt_enhancer` | `intermediate` | text |
+| | `text_to_video_audio` | `final` | |
+| `minimax/enhance-prompt-with-image.json` | `prompt_enhancer` | `intermediate` | text |
+| | `keyframe_to_video_audio` | `final` | |
+| `minimax/generated-subject-reference.json` | `draw_subject` | `intermediate` | |
+| | `reference_to_video_audio` | `final` | |
+| `minimax/music-video.json` | `draw_singer` | `intermediate` | |
+| | `write_song` | `intermediate` | the soundtrack is muxed into the cut |
+| | `shot` (the `for_each` step) | `intermediate` | |
+| | `music_video` | `final` | |
+| `minimax/storyboard.json` | `board_1_launch`, `board_2_gutter`, `board_3_shore` | `intermediate` | boards |
+| | `voyage` | `final` | |
+
+Steps not in the table (e.g. `slice`, `soundtrack`, `edit` in `music-video.json`, which have no `content_type`) are not saving steps and get nothing. Three templates already contain a `"subfolder"` key under a component's `from_pretrained_arguments` (`community-pipeline.json`, `ltx2/generative-upscale.json`, `multi-image-reference.json`) - that is a Hugging Face repo subfolder, unrelated; leave it alone. Only `result` blocks change.
+
+Example, `restore-faces.json` `restore` step, before:
+
+```json
+      "result": {
+        "content_type": "image/jpeg"
+      }
+```
+
+after:
+
+```json
+      "result": {
+        "content_type": "image/jpeg",
+        "subfolder": "final"
+      }
+```
+
+- [ ] **Step 4: Run the new test and the neighbours**
+
+Run: `source ./activate && python -m pytest tests/test_template_subfolders.py tests/test_examples.py tests/test_catalog_structure.py tests/test_catalog_shape.py -q`
+Expected: all PASS. `test_examples.py` validates every template against the schema and `validation_errors`, so a mistyped subfolder or a broken comma fails there; `test_catalog_structure.py`/`test_catalog_shape.py` pin that shapes and traits did not move (the catalog reads `result.content_type` only).
+
+- [ ] **Step 5: Run the whole suite**
+
+Run: `source ./activate && python -m pytest -q -x`
+Expected: PASS (5 skipped is normal).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tests/test_template_subfolders.py workflows/templates
+git commit -m "feat(templates): every multi-step template names its deliverable
+
+Every saving step of a template with two or more saving steps carries
+result.subfolder - final for the output the user is shown, intermediate
+for the scratch that went into it. tests/test_template_subfolders.py
+asserts the rule so it cannot drift and pins the packaged builtins as
+unmarked: a role is the parent's to assign.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: The plugin skills state the convention
+
+**Files:**
+- Modify: `plugins/dw/skills/minimax-h3/SKILL.md` (the *Run and judge* list, item 3)
+- Modify: `plugins/dw/skills/ltx-2.5/SKILL.md` (the *Run and judge* list, item 3)
+- Modify: `plugins/dw/skills/minimax-music3/SKILL.md` (the *Run and judge* list, item 3)
+- Test: `tests/test_plugin_skills.py`
+
+**Interfaces:**
+- Consumes: `skill_text(path)`, `SKILLS` (the sorted list of every `SKILL.md`), `H3_SKILL`, `PLUGIN_DIR`, `REPO_ROOT`, already defined at module level in `tests/test_plugin_skills.py`; `pytest` and `os` are already imported there; add `import json` beside them (the role test uses it) rather than importing inline.
+- Produces: nothing later tasks consume.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_plugin_skills.py`, after the last class:
+
+```python
+@pytest.mark.parametrize(
+    "path", SKILLS, ids=lambda p: os.path.basename(os.path.dirname(p))
+)
+def test_a_skill_states_the_subfolder_convention(path):
+    """The templates put the deliverable in `final` and the scratch in
+    `intermediate`; an agent reading get_job needs to know that, and one
+    composing a new workflow needs to keep it."""
+    text = skill_text(path)
+    assert "`subfolder`" in text, f"{path} does not name the subfolder field"
+    assert "`final`" in text and "`intermediate`" in text, (
+        f"{path} does not state the final/intermediate convention"
+    )
+    # the convention is stated where the manifest is read
+    assert text.index("`subfolder`") > text.index("## Run and judge")
+
+
+def test_the_h3_skill_names_the_intermediate_steps_the_templates_mark():
+    """The skill says what the family's templates put in intermediate -
+    portraits, boards, the song; if a template's roles change the skill
+    must change with it."""
+    text = skill_text(H3_SKILL)
+    for name in ("dialogue-short", "music-video", "storyboard"):
+        path = os.path.join(REPO_ROOT, "workflows", "templates", "minimax", name + ".json")
+        with open(path, encoding="utf-8") as f:
+            spec = json.load(f)
+        finals = [
+            step["name"]
+            for step in spec["steps"]
+            if (step.get("result") or {}).get("subfolder") == "final"
+        ]
+        assert len(finals) == 1, (name, finals)
+        assert f"`{finals[0]}`" in text, f"the skill does not name {name}'s final step {finals[0]}"
+```
+
+- [ ] **Step 2: Run them to verify they fail**
+
+Run: `source ./activate && python -m pytest tests/test_plugin_skills.py -q -k "subfolder or intermediate_steps"`
+Expected: 4 FAIL (three skills lack `` `subfolder` ``; the H3 role test fails on the first missing step name).
+
+- [ ] **Step 3: Add the paragraph to each skill**
+
+In each `SKILL.md`, the *Run and judge* list has an item 3 that begins with `` 3. `wait_for_job`, then `get_job` for the manifest. `` Extend **that item** (keep it item 3; append sentences to it, indented to the list's continuation indent of three spaces) with the family-specific text below. Wrap at the file's existing line width (about 80 columns).
+
+`plugins/dw/skills/minimax-h3/SKILL.md`, appended to item 3. **This skill has ~199 bytes of headroom under `SKILL_SIZE_LIMIT` (12288; check `wc -c` before and after)**, so the paragraph is short and item 4's existing list of the four portrait/board templates is left as is:
+
+```
+   Each entry carries `subfolder`: `final` is the deliverable (`episode`,
+   `music_video`, `voyage`), `intermediate` the scratch; keep that split in
+   anything you compose.
+```
+
+If the file still exceeds the cap, trim words from this paragraph only (the six backticked literals must stay); do not touch other sections.
+
+`plugins/dw/skills/ltx-2.5/SKILL.md`, appended to item 3:
+
+```
+   Each manifest entry carries `subfolder`: `templates/ltx2/generative-upscale`
+   puts `upscaled` in `final` and `low_resolution` in `intermediate`, and
+   `list_gallery(subfolder="final")` lists only deliverables. Keep the
+   convention in anything you compose from a template: the step whose output
+   the user will be shown is `final`, every other saving step `intermediate`.
+```
+
+`plugins/dw/skills/minimax-music3/SKILL.md`, appended to item 3:
+
+```
+   Each manifest entry carries `subfolder`: `templates/minimax/music-video`
+   puts the cut in `final` and the song, the singer's portrait and each shot
+   in `intermediate`, and `list_gallery(subfolder="final")` lists only
+   deliverables. Keep the convention in anything you compose from a template:
+   the step whose output the user will be shown is `final`, every other saving
+   step `intermediate`.
+```
+
+Every catalog name quoted above already resolves (`test_every_catalog_name_a_skill_quotes_resolves` checks); do not quote any other template.
+
+- [ ] **Step 4: Run the skill tests**
+
+Run: `source ./activate && python -m pytest tests/test_plugin_skills.py -q`
+Expected: all PASS - including `test_a_skill_has_a_triggering_description_under_the_size_cap`, which caps the skill's size; if it fails, tighten the paragraph rather than the cap.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/dw/skills tests/test_plugin_skills.py
+git commit -m "docs(skills): each family skill states the final/intermediate convention
+
+Where the skill reads the manifest it now says what the family's templates
+put in final and intermediate, that list_gallery(subfolder=) filters on it,
+and that a composed workflow keeps the convention. Pinned against the
+templates' actual roles.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Guide and CLAUDE.md, with the release note
+
+**Files:**
+- Modify: `docs/WORKFLOW_GUIDE.md` (section *Saying which output is the deliverable*, under *Authoring a workflow from an agent*)
+- Modify: `CLAUDE.md` (the `**Result subfolders**` bullet under *Critical Gotchas*)
+
+**Interfaces:** none.
+
+- [ ] **Step 1: The guide says the templates follow the convention**
+
+In `docs/WORKFLOW_GUIDE.md`, the paragraph in *Saying which output is the deliverable* that ends `Mark every saving step of a multi-step workflow; a one-step workflow needs nothing.` - append one sentence to that paragraph:
+
+```
+The shipped templates follow it: every template with two or more saving
+steps marks each one, so a workflow copied from a template starts with the
+roles in place.
+```
+
+- [ ] **Step 2: CLAUDE.md carries the release note**
+
+In `CLAUDE.md`, the `**Result subfolders**` bullet currently ends `` `file_base_name` may not contain a separator - it is a name, not a path ``. Change that line to end `it is a name, not a path.` (period on the same line - a period at the start of the next line renders as "path . Every") and append to the bullet (same indentation):
+
+```
+  Every `workflows/templates/**` file with two or more saving steps
+  marks each one `final`/`intermediate` (`tests/test_template_subfolders.py` pins the rule;
+  `dw/workflows/` builtins stay unmarked - a role is the parent's to assign). That moved
+  the templates' outputs into `<run>/final/` and `<run>/intermediate/`: an
+  `output:<template>/latest/x` reference keeps resolving but stops advancing past the last
+  pre-change run (`keep_output` is the stable form), and a seeded template's first run
+  after the change regenerates rather than hitting the step cache (the key includes
+  `result`). Those two, and a stray `subfolder` key becoming live, are the release-note
+  items beside the `shots` list change
+```
+
+(Check the rendered bullet reads as prose; the other gotcha bullets end without a period, this one now ends its last sentence `...the `shots` list change` without one too.)
+
+- [ ] **Step 3: Check the mirror rule**
+
+The CLAUDE.md *Type System* bullet for `result.subfolder` and the guide's section already agree from stage 2; this task adds a fact to each. Read both once after editing and confirm neither contradicts the other.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/WORKFLOW_GUIDE.md CLAUDE.md
+git commit -m "docs: the templates follow the subfolder convention; release-note items in CLAUDE.md
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: The design records stage 3
+
+**Files:**
+- Modify: `docs/proposals/output-folders.md` (line 3 status; *Steering consumers toward it* item 1)
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Status line**
+
+Change line 3 from
+
+```
+Status: **stages 1-2 (engine, server/MCP) implemented; stages 3-4 pending**. Written for MCP feedback ticket T016;
+```
+
+to
+
+```
+Status: **stages 1-3 (engine, server/MCP, steering) implemented; stage 4 (UI) pending**. Written for MCP feedback ticket T016;
+```
+
+- [ ] **Step 2: Correct the exemption in *Steering* item 1**
+
+In the *Steering consumers toward it* section, item 1, replace the sentences
+
+```
+A template whose saving steps are
+   all `workflow` steps over `builtin:` children (`compose-workflows`,
+   `sub-workflow`) is exempt: the files come from the child's steps, and
+   marking a builtin's step `final` would presume a role it does not have
+   - the builtins in `dw/workflows/` stay unmarked.
+```
+
+with
+
+```
+A `workflow` step is marked
+   like any other: its `result` block saves the parent's copy of the
+   child's return value (*Sub-workflows*, above), so the role is real and
+   the child's own steps never see it. The one exemption is the packaged
+   builtins in `dw/workflows/`, which stay unmarked - a builtin is a step
+   list a parent composes, and the role is the parent's to assign
+   (*implemented*: the drift test pins both halves; the earlier draft
+   exempted `compose-workflows` and `sub-workflow`, neither of which is a
+   `builtin:` composition). One consequence: a `workflow` step's
+   deliverable exists twice - the child's copy at the run root, the
+   parent's in `final/` - so `list_gallery(subfolder="final")` shows only
+   the parent's. The duplication is older than this design; it is now
+   distinguishable.
+```
+
+- [ ] **Step 2b: The *Tests* bullet matches the ruling**
+
+In the *Tests* section, the *Templates* bullet reads
+
+```
+- **Templates.** Every template with two or more saving steps, not exempt
+  as a `builtin:` composition, has a subfolder on each saving step.
+```
+
+Replace it with
+
+```
+- **Templates.** Every template with two or more saving steps has `final`
+  or `intermediate` on each saving step and at least one `final`; the
+  packaged builtins in `dw/workflows/` carry none.
+```
+
+Keep the paragraph's three-space continuation indent and wrap at the file's line width.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/proposals/output-folders.md
+git commit -m "docs: output-folders design marks stage 3 done; the builtin exemption is the builtins', not their parents'
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review
+
+**Spec coverage.** *Steering* 1 (templates + drift test) → Task 1; 2 (guide + CLAUDE.md mirror) → Task 3; 3 (tool descriptions) done in stage 2, nothing here; 4 (plugin skills) → Task 2. *Breaking changes* 3 and 4 (release note) → Task 3 Step 2. *Tests / Templates* → Task 1. *Phasing* stage 3 side note (`item:subfolder` derives a list field) - not exercised: no template uses an `item:` subfolder, by Global Constraint. Design status → Task 4.
+
+**Placeholders.** None: every edit is spelled out, every template step is in the table.
+
+**Consistency.** `saving_steps` and the ≥2 rule are the same in the test module and the Global Constraints. The three skill paragraphs quote only step names the table marks `final` (`episode`, `music_video`, `voyage`, `upscaled`) and Task 2's role test checks exactly those templates have one `final` step. The `for_each` steps `shot` in both cut templates have a single `result` block, so one edit marks every member.
diff --git a/docs/superpowers/plans/2026-09-12-output-subfolders-stage-4-ui.md b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-4-ui.md
new file mode 100644
index 00000000..546f136d
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-12-output-subfolders-stage-4-ui.md
@@ -0,0 +1,869 @@
+# Output Subfolders - Stage 4 (UI) 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:** Make `result.subfolder` visible to a person in the web UI: the gallery filters on it, the job page groups a run's results under `final/` and `intermediate/` headings, and the TypeScript types carry the field the server already sends.
+
+**Architecture:** Stages 1-3 landed the field everywhere the server speaks - every gallery entry, manifest entry and `step_end` event carries `subfolder` (`''` when a step chose none). Stage 4 is read-only consumption of that: the types learn the field (Task 1), `ui/src/lib/results.ts` learns to section step groups by subfolder (Task 2, pure function, vitest), `JobPage.svelte` renders the sections (Task 3), and `GalleryPage.svelte` grows a `<select>` beside its text filter (Task 4). The editor needs no work: its Monaco JSON views read the live `/api/schema`, which has described `result.subfolder` since stage 1. Docs close the stage (Task 5).
+
+**Tech Stack:** Svelte 5 (runes), TypeScript, vitest + @testing-library/svelte, from `ui/`. Checks: `npm run check`, `npm run lint`, `npm test`. `ui/dist` is git-ignored and built on release - do not commit a build.
+
+**Spec:** `docs/proposals/output-folders.md` - sections *The web UI* (~line 266), *Phasing* item 4, *Tests* → UI bullet.
+
+## Global Constraints
+
+- The field is `subfolder` on every surface; `''` means "at the run root". The engine treats no name specially and there is no default - the UI may *order* by the `final`/`intermediate` convention but must render any value.
+- Spec, *The web UI*: "Gallery: a second, smaller filter for `subfolder` beside the folder filter, fed by `subfolders`, defaulting to everything. `grouping.ts` is unchanged - the server still supplies `folder`." Ruling for this plan: the gallery page loads the whole listing once (`api.gallery()`, `?limit=100000`) and filters client-side, so the control is fed by the distinct `subfolder` values of the loaded entries - the same set the server's `subfolders` lists - and no second request is made. The existing test `fetches the gallery listing exactly once on mount` stays as it is. Task 5 records this in the design.
+- Spec, *The web UI*: "Job page: the manifest it already renders is grouped under headings by `subfolder` when any entry has a non-empty one; unchanged otherwise." "Unchanged otherwise" is binding: a run with every `subfolder === ''` (every pre-stage-1 job in history) renders exactly the DOM it renders today.
+- Spec, *Phasing* 4: grouping is "live from `step_end`, confirmed from the manifest" - a `step_end` event's `subfolder` places the group while the job runs; the manifest entry's value wins once it arrives.
+- Spec, *Tests* UI: "Gallery subfolder filter and job-page grouping (vitest)."
+- `ui/CLAUDE.md` design system: mono (`--font-mono`) for anything the engine resolves literally - a subfolder name is one; sentence case, no ALL-CAPS labels; no accent colour; `--live` only for what is running. A `<select>` takes the global `select` style in `app.css` - no new colours.
+- The gallery's folder grouping (`FolderGroups`, `folder`, `strip_run_id`) is untouched.
+- A historical job whose manifest entries predate stage 1 has no `subfolder` key: the type is optional on `ManifestEntry` and the code reads `entry.subfolder ?? ''`. `GalleryFile.subfolder` is required - the server always sends it.
+- Only the files this plan names change. No server, engine or MCP change; no `ui/e2e` change (the fixture writes unfoldered runs, and both spec files still pass).
+- Commit trailer on every commit: `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`.
+- Run `npm test`, `npm run check` and `npm run lint` from `ui/` before every commit that touches `ui/`.
+
+---
+
+## File map
+
+| File | Change |
+|---|---|
+| `ui/src/lib/types.ts` | `subfolder?: string` on `ManifestEntry`; new `StepEndEvent`; `subfolder: string` on `GalleryFile` |
+| `ui/src/lib/results.ts` | step groups carry `subfolder`; new `sectionBySubfolder` |
+| `ui/src/lib/results.test.ts` | tests for both |
+| `ui/src/lib/pages/JobPage.svelte` | render sections |
+| `ui/src/lib/pages/JobPage.test.ts` | **new** - rendering test for the sectioned and unsectioned cases |
+| `ui/src/lib/pages/GalleryPage.svelte` | subfolder `<select>` |
+| `ui/src/lib/pages/GalleryPage.test.ts` | `file()` factory gains `subfolder`; filter tests |
+| `docs/SERVER.md`, `docs/proposals/output-folders.md`, `CLAUDE.md` | one sentence each |
+
+---
+
+### Task 1: The types carry `subfolder`
+
+**Files:**
+- Modify: `ui/src/lib/types.ts:14-35` (`ManifestEntry`, `JobEvent`) and `:198-206` (`GalleryFile`)
+- Modify: `ui/src/lib/pages/GalleryPage.test.ts:16-24` (the `file()` factory, so `npm run check` stays green)
+
+**Interfaces:**
+- Produces: `ManifestEntry.subfolder?: string`; `StepEndEvent` (below); `GalleryFile.subfolder: string`. Tasks 2-4 import these.
+
+- [ ] **Step 1: Edit `ui/src/lib/types.ts`**
+
+Replace the `ManifestEntry` and `JobEvent` interfaces with:
+
+```ts
+export interface ManifestEntry {
+  step: string
+  files: string[]
+  /** The step was served from the step cache: these files are an earlier
+   * run's, republished, and nothing was generated for them this time. */
+  reused?: boolean
+  /** The in-run subfolder the step's `result.subfolder` chose - `final`,
+   * `intermediate`, any relative path - `''` when it chose none. Absent
+   * only on a job recorded before the field existed. */
+  subfolder?: string
+}
+```
+
+```ts
+export interface JobEvent {
+  seq: number
+  event: string
+  [key: string]: unknown
+}
+
+/** The `step_end` event, as the job page reads it: what the step saved and
+ * where, before the manifest confirms it. */
+export interface StepEndEvent extends JobEvent {
+  event: 'step_end'
+  step: string
+  files?: string[]
+  subfolder?: string
+  reused?: boolean
+}
+```
+
+In `GalleryFile`, after `folder: string` add:
+
+```ts
+  /** What followed the run id in the file's path - the `final` /
+   * `intermediate` a step's `result.subfolder` chose, `''` for none. */
+  subfolder: string
+```
+
+- [ ] **Step 2: Update the gallery test factory**
+
+In `ui/src/lib/pages/GalleryPage.test.ts` the `file()` helper builds a `GalleryFile`; it now fails `npm run check` without the new field. Replace it with:
+
+```ts
+const file = (name: string, subfolder = ''): GalleryFile => ({
+  name,
+  folder: name.includes('/') ? name.split('/')[0] : '',
+  subfolder,
+  url: `/outputs/${name}`,
+  kind: 'image',
+  size: 1024,
+  mtime: 1,
+  label: name.split('/').pop()!.split('.')[0],
+})
+```
+
+- [ ] **Step 3: Check and test**
+
+Run from `ui/`: `npm run check && npm run lint && npm test`
+Expected: all green (144 tests). `npm run check` must report 0 errors - grep the codebase for any other `GalleryFile` literal (`grep -rn "kind: 'image'" ui/src`) and add `subfolder: ''` wherever one is built.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add ui/src/lib/types.ts ui/src/lib/pages/GalleryPage.test.ts
+git commit -m "feat(ui): the manifest, step_end and gallery types carry subfolder
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: `results.ts` sections step groups by subfolder
+
+**Files:**
+- Modify: `ui/src/lib/results.ts`
+- Test: `ui/src/lib/results.test.ts`
+
+**Interfaces:**
+- Consumes: `ManifestEntry.subfolder?`, `StepEndEvent` from Task 1.
+- Produces:
+  ```ts
+  export interface StepGroup { step: string; files: string[]; reused: boolean; subfolder: string }
+  export function groupResultFiles(manifest: ManifestEntry[] | undefined, events: JobEvent[]): StepGroup[]
+  export interface SubfolderSection { subfolder: string; groups: StepGroup[] }
+  export function sectionBySubfolder(groups: StepGroup[]): SubfolderSection[]
+  ```
+  `sectionBySubfolder` returns **one** section with `subfolder: ''` when no group has a subfolder (the "unchanged otherwise" case, so the page can test `sections.length > 1 || sections[0].subfolder !== ''` to decide whether to show headings). Otherwise one section per distinct subfolder in first-appearance order, except that `final` is hoisted to the front - the deliverable is what a person opened the page for. Task 3 relies on exactly this ordering.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `ui/src/lib/results.test.ts` (and add `sectionBySubfolder` to the import from `./results`; update the `stepEnd` helper to take an optional subfolder):
+
+```ts
+const stepEnd = (step: string, files: string[], subfolder?: string): JobEvent =>
+  ({ seq: 0, event: 'step_end', step, files, subfolder }) as unknown as JobEvent
+```
+
+```ts
+describe('groupResultFiles subfolder', () => {
+  it('places a group from the live step_end and lets the manifest confirm it', () => {
+    const groups = groupResultFiles(
+      [{ step: 'episode', files: ['final/e.mp4'], subfolder: 'final' }],
+      [stepEnd('episode', ['final/e.mp4'], 'final')],
+    )
+    expect(groups).toEqual([
+      { step: 'episode', files: ['final/e.mp4'], reused: false, subfolder: 'final' },
+    ])
+  })
+
+  it('reads the subfolder from the stream alone while the job runs', () => {
+    const groups = groupResultFiles(undefined, [
+      stepEnd('shot', ['intermediate/s.mp4'], 'intermediate'),
+    ])
+    expect(groups[0].subfolder).toBe('intermediate')
+  })
+
+  it('treats a manifest entry without the field as the run root', () => {
+    const groups = groupResultFiles([{ step: 'old', files: ['a.png'] }], [])
+    expect(groups[0].subfolder).toBe('')
+  })
+
+  it('lets the manifest win when it names a different subfolder', () => {
+    const groups = groupResultFiles(
+      [{ step: 's', files: ['final/x.png'], subfolder: 'final' }],
+      [stepEnd('s', ['final/x.png'], '')],
+    )
+    expect(groups[0].subfolder).toBe('final')
+  })
+})
+
+describe('sectionBySubfolder', () => {
+  const group = (step: string, subfolder: string) => ({
+    step,
+    files: [`${subfolder ? subfolder + '/' : ''}${step}.png`],
+    reused: false,
+    subfolder,
+  })
+
+  it('returns one root section when no group has a subfolder', () => {
+    const sections = sectionBySubfolder([group('a', ''), group('b', '')])
+    expect(sections).toEqual([
+      { subfolder: '', groups: [group('a', ''), group('b', '')] },
+    ])
+  })
+
+  it('returns one root section for no groups at all', () => {
+    expect(sectionBySubfolder([])).toEqual([{ subfolder: '', groups: [] }])
+  })
+
+  it('sections by subfolder in first-appearance order, final first', () => {
+    const sections = sectionBySubfolder([
+      group('draw', 'intermediate'),
+      group('shot', 'intermediate'),
+      group('episode', 'final'),
+      group('notes', ''),
+    ])
+    expect(sections.map((s) => s.subfolder)).toEqual(['final', 'intermediate', ''])
+    expect(sections[1].groups.map((g) => g.step)).toEqual(['draw', 'shot'])
+  })
+
+  it('keeps any name the engine accepted, not just the convention', () => {
+    const sections = sectionBySubfolder([
+      group('a', 'shots/act-1'),
+      group('b', 'final'),
+    ])
+    expect(sections.map((s) => s.subfolder)).toEqual(['final', 'shots/act-1'])
+  })
+})
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run from `ui/`: `npx vitest run src/lib/results.test.ts`
+Expected: FAIL - `sectionBySubfolder` is not exported; the `groupResultFiles` equality fails on the missing `subfolder` key.
+
+- [ ] **Step 3: Implement**
+
+Replace `ui/src/lib/results.ts` with:
+
+```ts
+import type { JobEvent, ManifestEntry, StepEndEvent } from './types'
+
+/** One step's output files, with where in the run directory they landed. */
+export interface StepGroup {
+  step: string
+  files: string[]
+  reused: boolean
+  /** The step's `result.subfolder` - `''` for the run root. */
+  subfolder: string
+}
+
+/** A run's output files, grouped by the step that produced them. The
+ * step_end stream carries the association live; the manifest confirms it
+ * at the end - merged here so the grouping never flattens (the old
+ * behavior pooled every file into one bag). */
+export function groupResultFiles(
+  manifest: ManifestEntry[] | undefined,
+  events: JobEvent[],
+): StepGroup[] {
+  const order: string[] = []
+  const byStep = new Map<string, Set<string>>()
+  // Only the manifest knows a step was served from the step cache; the
+  // live step_end stream carries files but not that flag
+  const reused = new Set<string>()
+  // Placed by the live step_end, confirmed by the manifest - the manifest
+  // is written last, so its value is the one that stands
+  const subfolder = new Map<string, string>()
+  const add = (step: string, files: string[], where: string | undefined) => {
+    if (!byStep.has(step)) {
+      byStep.set(step, new Set())
+      order.push(step)
+    }
+    const set = byStep.get(step)!
+    for (const file of files) set.add(file)
+    if (where !== undefined) subfolder.set(step, where)
+  }
+  for (const event of events) {
+    if (event.event === 'step_end') {
+      const end = event as StepEndEvent
+      add(end.step || '(unnamed)', end.files ?? [], end.subfolder)
+    }
+  }
+  for (const entry of manifest ?? []) {
+    add(entry.step, entry.files, entry.subfolder ?? '')
+    if (entry.reused) reused.add(entry.step)
+  }
+  return order
+    .map((step) => ({
+      step,
+      files: [...byStep.get(step)!],
+      reused: reused.has(step),
+      subfolder: subfolder.get(step) ?? '',
+    }))
+    .filter((group) => group.files.length > 0)
+}
+
+/** The step groups of one subfolder, under one heading on the job page. */
+export interface SubfolderSection {
+  subfolder: string
+  groups: StepGroup[]
+}
+
+/** Step groups sectioned by the subfolder they landed in. A run where no
+ * step chose one is a single root section, so the page renders as it did
+ * before the field existed. Otherwise sections follow first appearance,
+ * except `final` leads: by convention it is the deliverable, the thing the
+ * page was opened for. The engine treats no name specially - any other
+ * value is a section like the rest. */
+export function sectionBySubfolder(groups: StepGroup[]): SubfolderSection[] {
+  const order: string[] = []
+  const bySubfolder = new Map<string, StepGroup[]>()
+  for (const group of groups) {
+    if (!bySubfolder.has(group.subfolder)) {
+      bySubfolder.set(group.subfolder, [])
+      order.push(group.subfolder)
+    }
+    bySubfolder.get(group.subfolder)!.push(group)
+  }
+  if (order.every((s) => s === '')) return [{ subfolder: '', groups }]
+  const ordered = order.includes('final')
+    ? ['final', ...order.filter((s) => s !== 'final')]
+    : order
+  return ordered.map((subfolder) => ({
+    subfolder,
+    groups: bySubfolder.get(subfolder)!,
+  }))
+}
+```
+
+Then update the four existing `groupResultFiles` tests' expected objects to include `subfolder: ''` (they use `toEqual` on whole objects).
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run from `ui/`: `npx vitest run src/lib/results.test.ts && npm run check && npm run lint`
+Expected: PASS, 0 check errors. (`JobPage.svelte` still compiles: it reads `group.step`, `group.files`, `group.reused` only.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ui/src/lib/results.ts ui/src/lib/results.test.ts
+git commit -m "feat(ui): step groups carry subfolder; sectionBySubfolder puts final first
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: The job page renders results under subfolder headings
+
+**Files:**
+- Modify: `ui/src/lib/pages/JobPage.svelte:183-186` (derivations), `:346-395` (Results panel), `:526-533` (styles)
+- Create: `ui/src/lib/pages/JobPage.test.ts`
+
+**Interfaces:**
+- Consumes: `sectionBySubfolder`, `StepGroup`, `SubfolderSection` from Task 2.
+
+Background for the implementer: `JobPage.svelte` reads a job by id from the router, fetches `api.getJob(id)` and streams events; `fileGroups` (line ~184) is `groupResultFiles(job?.manifest, events)`. The Results panel (line ~346) iterates `fileGroups`, shows an `<h3 class="stephead muted">` per step when there is more than one group, and lists the files in a `.media` flex row, labelling each by `file.split('/').pop()` - which is why a `final/x.png` reads as `x.png`; the subfolder heading is what tells the reader where it is.
+
+- [ ] **Step 1: Write the failing rendering test**
+
+Create `ui/src/lib/pages/JobPage.test.ts`. The page's whole mount surface, read from `JobPage.svelte`'s `<script>`: it takes `jobId` as a **prop** (no router mock needed - `go` from `../router.svelte` is only called on rerun); on mount it calls `api.getJobWorkflow(jobId)` (the flow-view definition; the code reads `result.definition` and `result.seed_variable`, so resolve it to `{ definition: null, seed_variable: null }`), then `api.getJob(jobId)`, and unless `detail.historical` it opens `streamJobEvents(jobId, -1, onEvent, onEnd)` - a **named export** of `../api`, not a method on `api`. `outputUrl(path, jobId, workspace)` and `ApiError` are also named imports from `../api`; `FlowView` renders only when `definition` is non-null, so it needs no fixture.
+
+```ts
+import { cleanup, render, screen, waitFor, within } from '@testing-library/svelte'
+import { afterEach, expect, it, vi } from 'vitest'
+import JobPage from './JobPage.svelte'
+import type { JobDetail, JobEvent } from '../types'
+
+const detail = vi.hoisted(() => ({ job: null as JobDetail | null }))
+// The live stream's callback, captured so a test can push step_end events
+const stream = vi.hoisted(() => ({
+  onEvent: null as ((event: JobEvent) => void) | null,
+}))
+
+vi.mock('../api', () => ({
+  ApiError: class ApiError extends Error {},
+  api: {
+    getJob: vi.fn(() => Promise.resolve(detail.job)),
+    getJobWorkflow: vi.fn(() =>
+      Promise.resolve({ definition: null, seed_variable: null }),
+    ),
+  },
+  outputUrl: (path: string) => `/outputs/${path}`,
+  streamJobEvents: (
+    _jobId: string,
+    _after: number,
+    onEvent: (event: JobEvent) => void,
+  ) => {
+    stream.onEvent = onEvent
+    return () => {}
+  },
+}))
+vi.mock('../toast', () => ({ notify: { error: vi.fn(), success: vi.fn() } }))
+
+const job = (manifest: JobDetail['manifest']): JobDetail => ({
+  id: 'j1',
+  workflow: 'templates/minimax/storyboard',
+  status: 'succeeded',
+  created_at: 1,
+  started_at: 1,
+  finished_at: 2,
+  workspace: 'default',
+  arguments: {},
+  warnings: [],
+  manifest,
+  error: null,
+  traceback: null,
+  event_count: 0,
+})
+
+afterEach(() => {
+  cleanup()
+  stream.onEvent = null
+})
+
+it('groups a foldered run under final/ and intermediate/ headings, final first', async () => {
+  detail.job = job([
+    { step: 'board_1', files: ['intermediate/b1.png'], subfolder: 'intermediate' },
+    { step: 'voyage', files: ['final/voyage.mp4'], subfolder: 'final' },
+  ])
+  render(JobPage, { jobId: 'j1' })
+  const headings = await waitFor(() => {
+    const found = screen.getAllByRole('heading', { level: 3 })
+    expect(found.length).toBeGreaterThanOrEqual(2)
+    return found
+  })
+  expect(headings.map((h) => h.textContent?.trim())).toEqual(['final/', 'intermediate/'])
+  // Step names drop to h4 under a subfolder heading
+  expect(
+    screen.getAllByRole('heading', { level: 4 }).map((h) => h.textContent?.trim()),
+  ).toEqual(['voyage', 'board_1'])
+})
+
+it('renders an unfoldered run exactly as before: step headings, no subfolder heading', async () => {
+  detail.job = job([
+    { step: 'generate', files: ['a.png'] },
+    { step: 'upscale', files: ['a_big.png'], subfolder: '' },
+  ])
+  render(JobPage, { jobId: 'j1' })
+  await waitFor(() => expect(screen.getByText('upscale')).toBeTruthy())
+  expect(
+    screen.getAllByRole('heading', { level: 3 }).map((h) => h.textContent?.trim()),
+  ).toEqual(['generate', 'upscale'])
+  expect(screen.queryByRole('heading', { level: 4 })).toBeNull()
+  expect(screen.queryByText(/\/$/)).toBeNull()
+})
+
+it('places a live step_end under its subfolder before the manifest arrives', async () => {
+  detail.job = { ...job([]), status: 'running', finished_at: null }
+  render(JobPage, { jobId: 'j1' })
+  await waitFor(() => expect(stream.onEvent).not.toBeNull())
+  stream.onEvent!({
+    seq: 1,
+    event: 'step_end',
+    step: 'episode',
+    files: ['final/e.mp4'],
+    subfolder: 'final',
+  })
+  await waitFor(() =>
+    expect(screen.getByRole('heading', { level: 3, name: 'final/' })).toBeTruthy(),
+  )
+})
+```
+
+`jobId` is a prop, so each test mounts with `render(JobPage, { jobId: 'j1' })`. The Results panel's `<h3 class="stephead">` is the only `<h3>` in `JobPage.svelte` today (the *Progress*/*Workflow*/*Error*/*Log* panels use `<h2>`), so the unscoped heading queries are exact; if the `../toast` mock's shape is off, read `ui/src/lib/toast.ts` for the `notify` members and mock every one the page calls. `within` is imported for the case the reviewer asks the queries be scoped to the Results panel - drop the import if unused (lint fails on it).
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run from `ui/`: `npx vitest run src/lib/pages/JobPage.test.ts`
+Expected: the first and third tests FAIL (no `final/` heading, no h4); the second PASSES already (it pins the unchanged case).
+
+- [ ] **Step 3: Implement the sectioned Results panel**
+
+In the `<script>` of `JobPage.svelte`, after `fileGroups`:
+
+```ts
+  import { groupResultFiles, sectionBySubfolder } from '../results'
+```
+(extend the existing import on line 12), and
+
+```ts
+  // Sections by result.subfolder - one root section, no heading, when no
+  // step chose one, so an older run renders as it always did
+  const sections = $derived(sectionBySubfolder(fileGroups))
+  const sectioned = $derived(
+    sections.length > 1 || sections[0].subfolder !== '',
+  )
+```
+
+Replace the `{#each fileGroups as group (group.step)} … {/each}` block inside the Results panel (keep the `<h2>Results</h2>` and the `allReused` note above it) with:
+
+```svelte
+      {#each sections as section (section.subfolder)}
+        {#if sectioned}
+          <h3 class="subhead">
+            {section.subfolder === '' ? '(run root)' : `${section.subfolder}/`}
+          </h3>
+        {/if}
+        {#each section.groups as group (group.step)}
+          {#if fileGroups.length > 1}
+            <svelte:element
+              this={sectioned ? 'h4' : 'h3'}
+              class="stephead muted"
+            >
+              {group.step}
+              {#if group.reused && !allReused}
+                <span
+                  class="muted"
+                  title="served from the step cache - an
+                       earlier run's files, nothing generated for this step"
+                  >· reused</span
+                >
+              {/if}
+            </svelte:element>
+          {/if}
+          <div class="media">
+            {#each group.files as file (file)}
+              {#if isImage(file)}
+                <a
+                  class="frame plain"
+                  href={fileUrl(file)}
+                  target="_blank"
+                  title={file.split('/').pop()}
+                  ><img src={fileUrl(file)} alt={file.split('/').pop()} /></a
+                >
+              {:else if isVideo(file)}
+                <span class="frame">
+                  <!-- svelte-ignore a11y_media_has_caption -->
+                  <video src={fileUrl(file)} controls loop></video>
+                </span>
+              {:else}
+                <a class="filelink" href={fileUrl(file)} target="_blank"
+                  >{file.split('/').pop()}</a
+                >
+              {/if}
+            {/each}
+          </div>
+        {/each}
+      {/each}
+```
+
+The inner file markup is the existing markup, moved one level in - do not change it. `'(run root)'` mirrors the prompt editor's `(root)` option and the gallery's `''` folder; it only ever shows beside a real subfolder heading.
+
+Styles - add beside `.stephead`:
+
+```css
+  .subhead {
+    font-size: var(--t-sm);
+    text-transform: none;
+    margin: var(--space-3) 0 var(--space-1);
+  }
+  .subhead:first-of-type {
+    margin-top: 0;
+  }
+  .subhead + .stephead {
+    margin-top: 0;
+  }
+```
+
+and extend `.stephead` itself with the heading treatment `app.css` gives `h1, h2, h3` only - an `h4` would otherwise fall back to the browser's sans bold, and a step name is engine-resolved, so mono:
+
+```css
+  .stephead {
+    font-family: var(--font-mono);
+    font-weight: 600;
+    line-height: 1.15;
+    letter-spacing: -0.01em;
+    font-size: 0.78rem;
+    text-transform: none;
+    margin: var(--space-3) 0 var(--space-2);
+  }
+```
+
+(No change in the `h3` case - those values are what the global rule already gives it. Do not edit `app.css`.) `.subhead` is an `h3`, so `final/` is already mono. `.stephead:first-of-type` is per element type: in the sectioned case it matches the first `h4.stephead` in the panel and sets `margin-top: 0`, the same thing `.subhead + .stephead` sets - redundant there, not inert. Keep both rules: the second and later sections' first `h4` rely on `.subhead + .stephead`.
+
+- [ ] **Step 4: Run the tests, check and lint**
+
+Run from `ui/`: `npx vitest run src/lib/pages/JobPage.test.ts && npm test && npm run check && npm run lint`
+Expected: all PASS, 0 errors. If `svelte-check` complains about `this={…}` on `svelte:element` with a class attribute, the attribute order is fine in Svelte 5 - re-read the message; it is more likely an unused-import or an a11y note.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ui/src/lib/pages/JobPage.svelte ui/src/lib/pages/JobPage.test.ts
+git commit -m "feat(ui): the job page groups results under final/ and intermediate/ headings
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: The gallery filters by subfolder
+
+**Files:**
+- Modify: `ui/src/lib/pages/GalleryPage.svelte:22-25` (state), `:87-93` (`visible`), `:276-281` (`.head`), `:305-319` (`Select all` label, `FolderGroups filterActive`), `:479-482` (styles)
+- Test: `ui/src/lib/pages/GalleryPage.test.ts`
+
+**Interfaces:**
+- Consumes: `GalleryFile.subfolder` (Task 1); the `file(name, subfolder)` factory (Task 1).
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `ui/src/lib/pages/GalleryPage.test.ts`:
+
+```ts
+it('offers no subfolder control when nothing was written to one', async () => {
+  await renderGallery()
+  expect(screen.queryByRole('combobox', { name: 'subfolder' })).toBeNull()
+})
+
+it('lists the subfolders the outputs landed in and filters the grid by one', async () => {
+  listing.files = [
+    file('wf/run-1/final/deliverable.png', 'final'),
+    file('wf/run-1/intermediate/scratch.png', 'intermediate'),
+    file('wf/run-1/root.png', ''),
+  ]
+  await renderGallery('wf/run-1/final/deliverable.png')
+
+  const pick = screen.getByRole('combobox', { name: 'subfolder' }) as HTMLSelectElement
+  expect([...pick.options].map((o) => o.textContent?.trim())).toEqual([
+    'all subfolders',
+    '(run root)',
+    'final/',
+    'intermediate/',
+  ])
+
+  pick.value = 'final'
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  await waitFor(() =>
+    expect(screen.queryByLabelText('select wf/run-1/intermediate/scratch.png')).toBeNull(),
+  )
+  expect(screen.getByLabelText('select wf/run-1/final/deliverable.png')).toBeTruthy()
+  expect(screen.queryByLabelText('select wf/run-1/root.png')).toBeNull()
+  // Select all takes what the subfolder filter leaves showing
+  screen.getByRole('button', { name: /select all matching \(1\)/i }).click()
+  await waitFor(() => expect(screen.getByText('1 selected')).toBeTruthy())
+})
+
+it('intersects the subfolder pick with the text filter', async () => {
+  listing.files = [
+    file('wf/run-1/final/a.png', 'final'),
+    file('wf/run-1/final/b.png', 'final'),
+    file('wf/run-1/intermediate/a.png', 'intermediate'),
+  ]
+  await renderGallery('wf/run-1/final/a.png')
+
+  const pick = screen.getByRole('combobox', { name: 'subfolder' }) as HTMLSelectElement
+  pick.value = 'final'
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  const filter = screen.getByPlaceholderText('filter…') as HTMLInputElement
+  filter.value = '/a.'
+  filter.dispatchEvent(new Event('input', { bubbles: true }))
+
+  await waitFor(() =>
+    expect(screen.queryByLabelText('select wf/run-1/final/b.png')).toBeNull(),
+  )
+  expect(screen.getByLabelText('select wf/run-1/final/a.png')).toBeTruthy()
+  expect(screen.queryByLabelText('select wf/run-1/intermediate/a.png')).toBeNull()
+})
+
+it('falls back to every subfolder when the picked one empties out', async () => {
+  listing.files = [
+    file('wf/run-1/final/only.png', 'final'),
+    file('wf/run-1/root.png', ''),
+  ]
+  await renderGallery('wf/run-1/final/only.png')
+  const pick = screen.getByRole('combobox', { name: 'subfolder' }) as HTMLSelectElement
+  pick.value = 'final'
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  await waitFor(() =>
+    expect(screen.queryByLabelText('select wf/run-1/root.png')).toBeNull(),
+  )
+
+  checkbox('wf/run-1/final/only.png').click()
+  screen.getByRole('button', { name: /^delete/i }).click()
+  await answerConfirm(true)
+
+  // The last final/ file is gone: the control goes with it and the grid
+  // shows everything again rather than an empty page pinned to a value
+  // that no longer exists
+  await waitFor(() =>
+    expect(screen.getByLabelText('select wf/run-1/root.png')).toBeTruthy(),
+  )
+  expect(screen.queryByRole('combobox', { name: 'subfolder' })).toBeNull()
+})
+```
+
+Note: the fourth test's "Delete" click is the bulk `Delete` in the `.picks` bar - the only button of that name before the dialog opens (the existing delete tests use the same `/^delete/i`), and `answerConfirm` is scoped to the dialog that follows.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run from `ui/`: `npx vitest run src/lib/pages/GalleryPage.test.ts`
+Expected: the first PASSES (no control exists yet); the other three FAIL on the missing combobox.
+
+- [ ] **Step 3: Implement**
+
+State (beside `let filter = $state('')`):
+
+```ts
+  // The in-run subfolder to show - null is every one. Only offered when
+  // some output landed in one; a workspace of unfoldered runs never sees
+  // the control
+  let subfolder = $state<string | null>(null)
+```
+
+Derivations - replace the `visible` derivation:
+
+```ts
+  // Every distinct subfolder in the listing, '' (the run root) included
+  // once anything is nested - the same set the server's `subfolders`
+  // reports, read off the entries so a delete updates it without a refetch
+  const subfolders = $derived(
+    [...new Set(files.map((f) => f.subfolder))].sort((a, b) =>
+      a.localeCompare(b),
+    ),
+  )
+  const subfolderOffered = $derived(subfolders.some((s) => s !== ''))
+  const filterActive = $derived(filter !== '' || subfolder !== null)
+  const visible = $derived(
+    files.filter(
+      (f) =>
+        f.name.toLowerCase().includes(filter.toLowerCase()) &&
+        (subfolder === null || f.subfolder === subfolder),
+    ),
+  )
+  // A pick that no longer exists (its last file deleted) means everything,
+  // not an empty grid pinned to a vanished value - and the control itself
+  // is reset, since a <select> whose value matches no option shows blank
+  $effect(() => {
+    if (subfolder !== null && !subfolders.includes(subfolder)) subfolder = null
+  })
+```
+
+Markup - in `.head`, after the filter input:
+
+```svelte
+  {#if subfolderOffered}
+    <select
+      class="subfolderpick"
+      aria-label="subfolder"
+      title="show only files a step saved to this subfolder of its run"
+      bind:value={subfolder}
+    >
+      <option value={null}>all subfolders</option>
+      {#each subfolders as s (s)}
+        <option value={s}>{s === '' ? '(run root)' : `${s}/`}</option>
+      {/each}
+    </select>
+  {/if}
+```
+
+Svelte 5 binds non-string option values (`null`) through `bind:value`; the test drives the control by setting `value = 'final'` and dispatching `change`, which reaches the same binding.
+
+`Select all` label: change `{filter ? ' matching' : ''}` to `{filterActive ? ' matching' : ''}`. `FolderGroups`: change `filterActive={filter !== ''}` to `filterActive={filterActive}`.
+
+Style, beside `.filter`:
+
+```css
+  .subfolderpick {
+    /* The global select rule is width: 100% - here it must share the row */
+    width: auto;
+    max-width: 200px;
+    font-family: var(--font-mono);
+    font-size: var(--t-sm);
+  }
+```
+
+(The option text is a path segment the engine wrote - mono, per the design system. Leave the global `select` colours alone; `width: auto` is what keeps the control beside the filter rather than wrapped onto a row of its own.) The `.filter` rule's `margin-left: auto` pushes the input to the right edge; the select lands after it and inherits the `.head` gap - check the layout reads "filter, then subfolder" and is not wrapped oddly at narrow widths; if the select should sit before the input, move it and keep `margin-left: auto` on `.filter`.
+
+- [ ] **Step 4: Run tests, check, lint**
+
+Run from `ui/`: `npm test && npm run check && npm run lint`
+Expected: all PASS, 0 errors. `fetches the gallery listing exactly once on mount` must still pass - the new derivations make no request.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ui/src/lib/pages/GalleryPage.svelte ui/src/lib/pages/GalleryPage.test.ts
+git commit -m "feat(ui): gallery filters by result subfolder
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Docs close the stage
+
+**Files:**
+- Modify: `docs/SERVER.md` (the *Jobs* bullet ~line 50 and the *Gallery* bullet ~line 79)
+- Modify: `docs/proposals/output-folders.md` (status line near the top; *The web UI* Gallery bullet; *Phasing* item 4)
+- Modify: `CLAUDE.md` (*Result subfolders* gotcha - one sentence)
+
+- [ ] **Step 1: `docs/SERVER.md`**
+
+In the *Jobs* bullet, the sentence "…and its result files as they land." wraps across two lines (~55-56, ending `they land.`); the next line begins "Jobs can be cancelled". Insert after `they land.` and before "Jobs can be cancelled", rewrapped to the bullet's width:
+
+```
+  A run whose steps chose a `result.subfolder` shows its results under
+  `final/` and `intermediate/` headings, the deliverable first; one that
+  chose none shows them as before.
+```
+
+In the *Gallery* bullet, after "…rather than listing each run separately," change the sentence so it reads:
+
+```
+  which the engine lays out as `<workflow>/<run id>/`. The folder filter groups a workflow's runs
+  together rather than listing each run separately, and a **subfolder** pick
+  beside the text filter - offered once any output landed in one - narrows
+  the grid to `final/`, `intermediate/` or whatever a step's
+  `result.subfolder` named; each run directory
+  also holds a `manifest.json` describing what produced it (see
+```
+
+- [ ] **Step 2: `docs/proposals/output-folders.md`**
+
+Status line: change `**stages 1-3 (engine, server/MCP, steering) implemented; stage 4 (UI) pending**` to `**all four stages (engine, server/MCP, steering, UI) implemented**`.
+
+*The web UI*, Gallery bullet - replace with:
+
+```
+- Gallery: a second, smaller filter for `subfolder` beside the text filter,
+  a `<select>` fed by the distinct `subfolder` values of the loaded entries
+  (the same set the server's `subfolders` lists - the page already holds
+  the whole listing and filters client-side, so no second request), shown
+  only once some output landed in one, defaulting to everything. The two
+  filters intersect. `grouping.ts` is unchanged - the server still supplies
+  `folder`.
+- Job page: the manifest it already renders is grouped under headings by
+  `subfolder` when any entry has a non-empty one - `final/` first, then in
+  order of appearance, `(run root)` for the empty value - with the step
+  headings one level down; unchanged otherwise. The grouping is live from
+  `step_end` and confirmed by the manifest (`sectionBySubfolder` in
+  `ui/src/lib/results.ts`).
+```
+
+*Phasing* item 4 - change "`subfolder` on the `ManifestEntry` and `JobEvent` types" to "`subfolder` on the `ManifestEntry` and `GalleryFile` types and a `StepEndEvent` subtype of `JobEvent`" (the `JobEvent` type is an index signature, so the field lives on a typed subtype).
+
+- [ ] **Step 3: `CLAUDE.md`**
+
+In the *Result subfolders* gotcha, after "…MCP `list_gallery(subfolder=)` filter on it." insert before "`file_base_name` may not contain a separator":
+
+```
+  The web UI reads the field only: the gallery page offers a subfolder pick
+  once any entry has one, and the job page sections results under `final/` /
+  `intermediate/` headings (`sectionBySubfolder`, `ui/src/lib/results.ts`),
+  unchanged for a run that chose none.
+```
+
+Keep the bullet's wrapping width (~90 columns) and make sure the inserted sentence joins the paragraph with a period on both sides.
+
+- [ ] **Step 4: Check nothing else pins the old status**
+
+Run: `grep -rn "stage 4 (UI) pending\|stages 1-3" docs/proposals docs/SERVER.md docs/MCP.md docs/WORKFLOW_GUIDE.md CLAUDE.md`
+Expected: no matches. (The plans under `docs/superpowers/` legitimately mention both phrases - they are history, not status.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/SERVER.md docs/proposals/output-folders.md CLAUDE.md
+git commit -m "docs: the UI stage of output subfolders is in; design marks all four stages done
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review
+
+- **Spec coverage.** *The web UI* Gallery → Task 4; Job page → Tasks 2-3; Editor → none needed (schema-driven, stated in Architecture). *Phasing* 4: types → Task 1; gallery control → Task 4; grouping live/confirmed → Task 2 (`subfolder` map, manifest wins) + Task 3 third test. *Tests* UI bullet → `results.test.ts`, `JobPage.test.ts`, `GalleryPage.test.ts`. Docs → Task 5.
+- **Placeholders.** None: Task 3's mock surface was read off `JobPage.svelte` (`getJobWorkflow`, `getJob`, named `streamJobEvents`/`outputUrl`/`ApiError`, `jobId` prop).
+- **Type consistency.** `StepGroup.subfolder: string`, `SubfolderSection { subfolder, groups }`, `sectionBySubfolder(groups)` used identically in Tasks 2, 3 and 5. `file(name, subfolder = '')` from Task 1 is what Task 4's tests call. `GalleryFile.subfolder` required; `ManifestEntry.subfolder` optional and read with `?? ''` in Task 2 - matches Global Constraints.
diff --git a/dw/host_memory.py b/dw/host_memory.py
new file mode 100644
index 00000000..89b48340
--- /dev/null
+++ b/dw/host_memory.py
@@ -0,0 +1,134 @@
+"""What the worker process and its machine are using in host RAM.
+
+`device_memory_stats` answers for the accelerator, which on this project is
+often the least informative half of the question: the templates here keep
+weights in host memory by design (`offload: "sequential"`, `group_offload`),
+so a card can sit near-empty through a generation whose weights are very
+much resident somewhere. This module is the other half.
+
+Three methods, in order, none of them required: psutil when it happens to be
+installed (a transitive dependency here, not a declared one), Linux's
+`/proc` otherwise, and `resource.getrusage` for the process's peak, which is
+available on every POSIX platform. Nothing raises - a reading that cannot be
+taken is reported as None rather than failing the call that asked for it.
+"""
+
+import logging
+import os
+
+logger = logging.getLogger("dw")
+
+__all__ = ["host_memory_stats", "host_memory_fields"]
+
+_MB = 1024.0 * 1024.0
+
+
+def host_memory_stats():
+    """Snapshot of host memory for this process and the machine it is on.
+
+    Returns:
+        dict with keys, any of which may be None when the platform cannot
+        answer:
+            rss_mb (float or None): resident set size of *this* process -
+                in the worker, the weights it is holding
+            peak_rss_mb (float or None): the high-water mark of the above,
+                which is what says whether a run that has finished released
+                what it took
+            total_mb (float or None): the machine's physical memory
+            available_mb (float or None): what can be handed out without
+                swapping - MemAvailable on Linux, not free memory, since
+                page cache is reclaimable
+    """
+    stats = {
+        "rss_mb": None,
+        "peak_rss_mb": _peak_rss_mb(),
+        "total_mb": None,
+        "available_mb": None,
+    }
+
+    for method in (_psutil_stats, _proc_stats):
+        try:
+            reading = method()
+        except Exception as e:  # a memory reading is never worth an exception
+            logger.debug(f"Host memory via {method.__name__} failed: {e}")
+            continue
+        for key, value in reading.items():
+            if stats.get(key) is None and value is not None:
+                stats[key] = value
+        if all(stats[key] is not None for key in ("rss_mb", "total_mb")):
+            break
+
+    return stats
+
+
+def _psutil_stats():
+    import psutil
+
+    virtual = psutil.virtual_memory()
+    return {
+        "rss_mb": psutil.Process().memory_info().rss / _MB,
+        "total_mb": virtual.total / _MB,
+        "available_mb": virtual.available / _MB,
+    }
+
+
+def _proc_stats():
+    """Linux without psutil: /proc/self/statm for this process, /proc/meminfo
+    for the machine. Both absent elsewhere, which is what the None default
+    covers."""
+    reading = {"rss_mb": None, "total_mb": None, "available_mb": None}
+
+    try:
+        with open("/proc/self/statm", "r") as f:
+            pages = int(f.read().split()[1])
+        reading["rss_mb"] = pages * os.sysconf("SC_PAGE_SIZE") / _MB
+    except (OSError, ValueError, IndexError, AttributeError):
+        pass
+
+    wanted = {"MemTotal:": "total_mb", "MemAvailable:": "available_mb"}
+    try:
+        with open("/proc/meminfo", "r") as f:
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 2 and parts[0] in wanted:
+                    # meminfo is in kB
+                    reading[wanted[parts[0]]] = int(parts[1]) / 1024.0
+    except (OSError, ValueError):
+        pass
+
+    return reading
+
+
+def _peak_rss_mb():
+    """getrusage's high-water mark, in kB on Linux and bytes on macOS - the
+    one place in this module where the unit depends on the platform."""
+    try:
+        import resource
+        import sys
+
+        peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    except Exception:
+        return None
+    if not peak:
+        return None
+    return peak / _MB if sys.platform == "darwin" else peak / 1024.0
+
+
+# The memory payload's own names for the above, beside its gpu_* keys
+FIELD_NAMES = {
+    "rss_mb": "host_memory_rss_mb",
+    "peak_rss_mb": "host_memory_peak_rss_mb",
+    "total_mb": "host_memory_total_mb",
+    "available_mb": "host_memory_available_mb",
+}
+
+
+def host_memory_fields():
+    """host_memory_stats under the names the memory payload reports, with
+    the readings this platform cannot take left out rather than sent as
+    null - a key that is absent says "not measurable here", where a null
+    would read as "measured, and nothing"."""
+    stats = host_memory_stats()
+    return {
+        FIELD_NAMES[key]: value for key, value in stats.items() if value is not None
+    }
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index 8aeb29ae..c84be296 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -238,117 +238,150 @@ def load(self, shared_components):
             logger.info(f"Pre-loading module: {module_name}")
             importlib.import_module(module_name)
 
-        # Prepare arguments and load pipeline
-        from_pretrained_arguments = self.populate_from_pretrained_arguments(
-            self.device, shared_components
-        )
-        reused_components = self.resolve_reused_components(shared_components)
+        # A load that raises partway has already built some of what it was
+        # asked for - the pipeline itself, its quantized weights, a placement
+        # half applied - and none of that is reachable from the caller, which
+        # never received a pipeline. Left alone it stays resident until the
+        # exception is handled and something else happens to collect, so a
+        # retry loads its own copy on top of the last attempt's: three failures
+        # is three pipelines' worth of dead weight. Tear the attempt down here
+        # instead, then let the failure carry on
+        try:
+            # Prepare arguments and load pipeline
+            from_pretrained_arguments = self.populate_from_pretrained_arguments(
+                self.device, shared_components
+            )
+            reused_components = self.resolve_reused_components(shared_components)
 
-        # Adapters add weights to the components they attach to, and an offloading
-        # hook only streams the weights that existed when it was installed - so a
-        # pipeline that loads any is placed after they are on it, not at load
-        adapters_to_load = bool(self.pipeline_definition.get("loras", [])) or (
-            self.pipeline_definition.get("ip_adapter", None) is not None
-        )
+            # Adapters add weights to the components they attach to, and an offloading
+            # hook only streams the weights that existed when it was installed - so a
+            # pipeline that loads any is placed after they are on it, not at load
+            adapters_to_load = bool(self.pipeline_definition.get("loras", [])) or (
+                self.pipeline_definition.get("ip_adapter", None) is not None
+            )
 
-        # Load and configure the main pipeline
-        self.pipeline = load_component(
-            "pipeline",
-            self.configuration,
-            from_pretrained_arguments,
-            self.device,
-            reused_components,
-            defer_placement=adapters_to_load,
-        )
+            # Load and configure the main pipeline
+            self.pipeline = load_component(
+                "pipeline",
+                self.configuration,
+                from_pretrained_arguments,
+                self.device,
+                reused_components,
+                defer_placement=adapters_to_load,
+            )
 
-        # Enable attention slicing if explicitly requested or automatically on MPS
-        # MPS benefits from slicing since Metal shares system RAM with the GPU
-        if self.configuration.get("enable_attention_slicing", False) or (
-            get_device_type(self.device) == "mps"
-            and not self.configuration.get("disable_attention_slicing", False)
-        ):
-            # Modular pipelines have no attention slicing - on MPS this is applied
-            # automatically, so skip rather than fail when the pipeline lacks it
-            if has_method(self.pipeline, "enable_attention_slicing"):
-                logger.debug("Enabling attention slicing for pipeline")
-                self.pipeline.enable_attention_slicing()
-            else:
-                logger.debug(
-                    f"{type(self.pipeline).__name__} does not support attention slicing, skipping"
-                )
+            # Enable attention slicing if explicitly requested or automatically on MPS
+            # MPS benefits from slicing since Metal shares system RAM with the GPU
+            if self.configuration.get("enable_attention_slicing", False) or (
+                get_device_type(self.device) == "mps"
+                and not self.configuration.get("disable_attention_slicing", False)
+            ):
+                # Modular pipelines have no attention slicing - on MPS this is applied
+                # automatically, so skip rather than fail when the pipeline lacks it
+                if has_method(self.pipeline, "enable_attention_slicing"):
+                    logger.debug("Enabling attention slicing for pipeline")
+                    self.pipeline.enable_attention_slicing()
+                else:
+                    logger.debug(
+                        f"{type(self.pipeline).__name__} does not support attention slicing, skipping"
+                    )
 
-        # configure components that are not shared
-        self.configure_loaded_components()
+            # configure components that are not shared
+            self.configure_loaded_components()
 
-        # Apply SDNQ quantized matmul optimization to specified components
-        sdnq_optimize = self.configuration.get("sdnq_optimize", [])
-        if sdnq_optimize:
-            apply_sdnq_optimizations(self.pipeline, sdnq_optimize)
+            # Apply SDNQ quantized matmul optimization to specified components
+            sdnq_optimize = self.configuration.get("sdnq_optimize", [])
+            if sdnq_optimize:
+                apply_sdnq_optimizations(self.pipeline, sdnq_optimize)
 
-        # Enable diffusers built-in cache acceleration on transformer
-        cache_config = get_cache_configuration(self.configuration)
-        if cache_config is not None:
-            enable_cache_on_transformer(self.pipeline, cache_config)
+            # Enable diffusers built-in cache acceleration on transformer
+            cache_config = get_cache_configuration(self.configuration)
+            if cache_config is not None:
+                enable_cache_on_transformer(self.pipeline, cache_config)
 
-        # Configure the schedulers if specified - a pipeline that denoises two
-        # modalities against two schedules configures each of them separately
-        load_and_configure_scheduler(
-            self.pipeline_definition.get("scheduler", None), self.pipeline
-        )
-        load_and_configure_scheduler(
-            self.pipeline_definition.get("audio_scheduler", None),
-            self.pipeline,
-            "audio_scheduler",
-        )
+            # Configure the schedulers if specified - a pipeline that denoises two
+            # modalities against two schedules configures each of them separately
+            load_and_configure_scheduler(
+                self.pipeline_definition.get("scheduler", None), self.pipeline
+            )
+            load_and_configure_scheduler(
+                self.pipeline_definition.get("audio_scheduler", None),
+                self.pipeline,
+                "audio_scheduler",
+            )
 
-        self.publish_shared_components(shared_components)
+            self.publish_shared_components(shared_components)
 
-        # Load and configure LoRA models
-        load_loras(self.pipeline_definition.get("loras", []), self.pipeline)
+            # Load and configure LoRA models
+            load_loras(self.pipeline_definition.get("loras", []), self.pipeline)
 
-        # Load and configure IP-Adapter
-        load_ip_adapter(self.pipeline_definition.get("ip_adapter", None), self.pipeline)
+            # Load and configure IP-Adapter
+            load_ip_adapter(
+                self.pipeline_definition.get("ip_adapter", None), self.pipeline
+            )
 
-        # The adapters are on the pipeline now, so its offloading hooks can be
-        # installed over the weights they added
-        if adapters_to_load:
-            self.pipeline = place_component(
-                self.pipeline,
-                "pipeline",
-                self.configuration,
-                self.device,
-                # A modular pipeline's manager owns its placement, and the manager
-                # load_component gave it is the one it holds
-                getattr(self.pipeline, "_components_manager", None),
+            # The adapters are on the pipeline now, so its offloading hooks can be
+            # installed over the weights they added
+            if adapters_to_load:
+                self.pipeline = place_component(
+                    self.pipeline,
+                    "pipeline",
+                    self.configuration,
+                    self.device,
+                    # A modular pipeline's manager owns its placement, and the manager
+                    # load_component gave it is the one it holds
+                    getattr(self.pipeline, "_components_manager", None),
+                )
+
+            # Place the components the pipeline loaded itself, once everything that alters
+            # them - dtypes, adapters, quantized matmuls - has been applied. Offloading hooks
+            # installed before those would be fighting them
+            configure_components(
+                self.pipeline, self.configuration, self.device, reused_components
             )
 
-        # Place the components the pipeline loaded itself, once everything that alters
-        # them - dtypes, adapters, quantized matmuls - has been applied. Offloading hooks
-        # installed before those would be fighting them
-        configure_components(
-            self.pipeline, self.configuration, self.device, reused_components
-        )
+            # Set up random generator if needed - no_generator is a boolean, so an
+            # explicit false still gets a generator
+            if not self.configuration.get("no_generator", False):
+                logger.debug("Setting up random generator")
+                self.argument_template["generator"] = torch.Generator(
+                    self.device
+                ).manual_seed(self.pipeline_definition.get("seed", self.default_seed))
+
+            # Hand the first run a clean allocator. Loading churns the device even
+            # when little of the pipeline stays there - a quantization pass with
+            # 'quantization_device' set works on the accelerator and returns the
+            # weights to the host, and group offloading moves components off it
+            # again - and the cached blocks left behind are the wrong shape for
+            # inference. workflow.py does this between steps; a one-step workflow
+            # would otherwise run its only step on top of the loading debris
+            gc.collect()
+            empty_device_cache()
+        except BaseException:
+            self._discard_failed_load(shared_components)
+            raise
+
+        logger.debug("Pipeline loaded successfully")
+
+    def _discard_failed_load(self, shared_components):
+        """Drop everything a load that raised had built, and reclaim it.
 
-        # Set up random generator if needed - no_generator is a boolean, so an
-        # explicit false still gets a generator
-        if not self.configuration.get("no_generator", False):
-            logger.debug("Setting up random generator")
-            self.argument_template["generator"] = torch.Generator(
-                self.device
-            ).manual_seed(self.pipeline_definition.get("seed", self.default_seed))
-
-        # Hand the first run a clean allocator. Loading churns the device even
-        # when little of the pipeline stays there - a quantization pass with
-        # 'quantization_device' set works on the accelerator and returns the
-        # weights to the host, and group offloading moves components off it
-        # again - and the cached blocks left behind are the wrong shape for
-        # inference. workflow.py does this between steps; a one-step workflow
-        # would otherwise run its only step on top of the loading debris
+        Unpublishes as well as releases: a component shared before the failure
+        would otherwise be handed to a later step as a component of a pipeline
+        that does not exist. A name this pipeline reused rather than loaded
+        stays published - that entry belongs to the earlier pipeline that put
+        it there, which is still alive.
+        """
+        logger.info(f"Load of pipeline '{self.name}' failed - releasing what it built")
+        reused = set(self.component_names("reused_components"))
+        for shared_component_name in self.component_names("shared_components"):
+            if shared_component_name not in reused:
+                shared_components.pop(shared_component_name, None)
+        self.pipeline = None
+        self.argument_template.pop("generator", None)
         gc.collect()
         empty_device_cache()
 
-        logger.debug("Pipeline loaded successfully")
-
     def publish_shared_components(self, shared_components):
         """Store components that will be shared with other pipelines.
 
diff --git a/dw/repl.py b/dw/repl.py
index 868dad4e..ca52c4bd 100644
--- a/dw/repl.py
+++ b/dw/repl.py
@@ -258,6 +258,7 @@ def _print_memory_info(self, info):
         """Print formatted memory information"""
         if not info.get("gpu_available"):
             print("GPU not available")
+            self._print_host_memory(info)
             return
 
         print(f"\nGPU Memory Status:")
@@ -270,8 +271,24 @@ def _print_memory_info(self, info):
             print(f"  Total: {info.get('gpu_memory_total_mb', 0):.1f} MB")
 
         print(f"  Runs in this session: {info.get('run_count', 0)}")
+        self._print_host_memory(info)
         print()
 
+    def _print_host_memory(self, info):
+        """Host RAM, when the platform could be asked - with offloaded
+        weights the card says very little about what a run is holding."""
+        if "host_memory_rss_mb" not in info:
+            return
+        print(f"\nHost Memory:")
+        print(f"  Worker RSS: {info['host_memory_rss_mb']:.1f} MB")
+        if "host_memory_peak_rss_mb" in info:
+            print(f"  Worker peak RSS: {info['host_memory_peak_rss_mb']:.1f} MB")
+        if "host_memory_available_mb" in info:
+            print(
+                f"  Available: {info['host_memory_available_mb']:.1f} MB"
+                f" of {info.get('host_memory_total_mb', 0):.1f} MB"
+            )
+
 
 def main():
     """Start the REPL interface"""
diff --git a/dw/result.py b/dw/result.py
index fd9d7d9d..b837b9c1 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -13,7 +13,12 @@
 )
 from collections.abc import Mapping
 from .events import emit_phase
-from .security import validate_output_path, validate_string_input, SecurityError
+from .security import (
+    SecurityError,
+    validate_file_base_name,
+    validate_output_path,
+    validate_string_input,
+)
 
 logger = logging.getLogger("dw")
 
@@ -306,9 +311,11 @@ def save(self, output_dir, default_base_name):
         # Determine base filename with validation
         file_base_name = validated_base_name
         if "file_base_name" in self.result_definition:
-            custom_base = validate_string_input(
-                self.result_definition["file_base_name"],
-                max_length=MAX_BASE_NAME_LENGTH,
+            custom_base = validate_file_base_name(
+                validate_string_input(
+                    self.result_definition["file_base_name"],
+                    max_length=MAX_BASE_NAME_LENGTH,
+                )
             )
             file_base_name = custom_base + validated_base_name
 
diff --git a/dw/runs.py b/dw/runs.py
index 0587ac25..ac42818b 100644
--- a/dw/runs.py
+++ b/dw/runs.py
@@ -308,18 +308,41 @@ def is_run_id(segment):
     return bool(RUN_ID_PATTERN.match(segment or ""))
 
 
+def split_run_path(relative_path):
+    """The three parts of a run-relative path: (identity, run id, subfolder).
+
+    'ltx2/Gyre/20260905-181530-a1b2c3d4/final/still.png' ->
+    ('ltx2/Gyre', '20260905-181530-a1b2c3d4', 'final'). The run id is
+    found wherever it sits, not only as the last directory - a step's
+    'subfolder' puts segments after it. A path with no run id in it (the
+    flat layout) has its whole directory as identity and nothing else,
+    which is what it was before subfolders existed.
+
+    Only the first segment matching RUN_ID_PATTERN counts. A workflow
+    *file* named in that shape would produce a matching identity segment;
+    that is unsupported rather than impossible.
+    """
+    parts = [part for part in (relative_path or "").split("/") if part]
+    directory = parts[:-1]
+    for position, segment in enumerate(directory):
+        if is_run_id(segment):
+            return (
+                "/".join(directory[:position]),
+                segment,
+                "/".join(directory[position + 1 :]),
+            )
+    return "/".join(directory), "", ""
+
+
 def strip_run_id(relative_path):
     """The workflow identity a run-relative path belongs to.
 
-    'ltx2/Gyre/20260905-181530-a1b2c3d4/still-0.png' -> 'ltx2/Gyre'. A path
-    with no run id in it comes back with its own directory unchanged, which
-    is what a flat-layout output does.
+    'ltx2/Gyre/20260905-181530-a1b2c3d4/still-0.png' -> 'ltx2/Gyre', and
+    the same with a subfolder after the run id. A path with no run id in it
+    comes back with its own directory unchanged, which is what a
+    flat-layout output does.
     """
-    parts = [part for part in (relative_path or "").split("/") if part]
-    directory = parts[:-1]
-    if directory and is_run_id(directory[-1]):
-        directory = directory[:-1]
-    return "/".join(directory)
+    return split_run_path(relative_path)[0]
 
 
 def run_directory(output_dir, file_spec, workflow_id, run_id):
diff --git a/dw/security.py b/dw/security.py
index b34a2663..4e065e18 100644
--- a/dw/security.py
+++ b/dw/security.py
@@ -555,6 +555,61 @@ def validate_output_reference(name: str) -> str:
     )
 
 
+# A step's result 'subfolder': a relative path under the run directory. The
+# segment rule is OUTPUT_REFERENCE_PATTERN's, so every subfolder the engine
+# writes is one a later workflow can name with 'output:'. It also refuses a
+# backslash, which DANGEROUS_PATTERNS does not - '"final\\x"' would be one
+# directory on POSIX and two on Windows
+SUBFOLDER_PATTERN = r"^[\w][\w.-]*(/[\w][\w.-]*)*\Z"
+MAX_SUBFOLDER_LENGTH = 200
+
+
+def validate_subfolder(name: str) -> str:
+    """
+    Validate the shape of a result 'subfolder'.
+
+    Containment is checked separately, by the validate_output_path call
+    that joins it onto the run directory.
+
+    Args:
+        name: The subfolder as written in the workflow
+
+    Returns:
+        The validated name
+
+    Raises:
+        InvalidInputError: If the name is not a valid subfolder
+    """
+    return _validate_name(
+        name,
+        SUBFOLDER_PATTERN,
+        MAX_SUBFOLDER_LENGTH,
+        "Subfolder",
+        "a subfolder is one or more path segments under the run directory, "
+        "each starting with a letter, digit or underscore, like 'final' or "
+        "'shots/act-1'",
+    )
+
+
+def validate_file_base_name(name: str) -> str:
+    """
+    Validate a result 'file_base_name': a name, never a path.
+
+    A separator here used to pass validation and then fail at open() because
+    the directory did not exist. Placement is what 'subfolder' is for.
+
+    Raises:
+        InvalidInputError: If the name carries a path separator
+    """
+    if "/" in name or "\\" in name:
+        raise InvalidInputError(
+            f"Invalid file_base_name: {name} - a file_base_name is a name, not "
+            f"a path; to write into a subfolder of the run directory set "
+            f"'subfolder' on the result instead"
+        )
+    return name
+
+
 # A workspace's name: one path segment, starting with a word character, so
 # '..', hidden names and anything with a separator in it are all excluded
 # before the name is joined onto the workspace root
diff --git a/dw/server/app.py b/dw/server/app.py
index 34d98012..371c589d 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -64,7 +64,7 @@
 from ..result import read_embedded_metadata
 from ..media_info import probe_media
 from ..hub_cache import scan_models, delete_model, DownloadManager
-from ..runs import is_output_reference, resolve_output_reference, strip_run_id
+from ..runs import is_output_reference, resolve_output_reference, split_run_path
 from ..workspace import (
     ASSETS_SUBDIR,
     DEFAULT_WORKSPACE_NAME,
@@ -901,8 +901,11 @@ def list_jobs(
                     status_code=400, detail="limit must not be negative"
                 )
             # the newest are the interesting ones, and the list is oldest
-            # first - so the cut comes off the front, not the back
-            jobs = jobs[len(jobs) - limit :] if limit else []
+            # first - so the cut comes off the front, not the back. max(0, ...)
+            # because a limit above what matched is no cut at all: a bare
+            # negative start would be read from the end instead, and answer a
+            # limit of 12 against 9 matching jobs with the last 3 of them
+            jobs = jobs[max(0, len(jobs) - limit) :] if limit else []
         return {"jobs": jobs, "total": total}
 
     @app.get("/api/jobs/{job_id}")
@@ -1951,20 +1954,23 @@ def _served_url(path, ws, version=None):
 
     def _iter_gallery_files(root, group_runs=True):
         """Every media file under a directory tree. Yields (relative_name,
-        folder, kind, path) - relative_name always uses '/' so it
-        round-trips through a URL the same way on every platform.
+        folder, subfolder, kind, path) - relative_name always uses '/' so
+        it round-trips through a URL the same way on every platform.
 
         With group_runs (the gallery's own use, over the output directory):
         recurses into the per-workflow subfolders (dw/workflow.py's
         effective_output_dir writes each run under '<workflow
         identity>/<run id>/', and mirrors a workflow's position under a
-        'workflows' tree in the flat layout), and the folder a file is
-        grouped under drops the run id - a workflow run fifty times is one
-        folder in the filter, not fifty. Which run a file came from is still
-        in its name, and in the manifest beside it.
+        'workflows' tree in the flat layout). The folder a file is grouped
+        under is the identity - the run id is dropped, so a workflow run
+        fifty times is one folder in the filter, not fifty - and whatever
+        followed the run id is the subfolder, the part of the run a step's
+        'result.subfolder' put it in ('final', 'intermediate'). A flat-layout
+        path has no run id to anchor on, so its subfolder is '' and its
+        whole directory is the folder, as it always was.
 
         Without it (the asset library's use, which has no run ids to strip):
-        folder is just the plain relative directory."""
+        folder is just the plain relative directory and subfolder is ''."""
         for current, _dirs, names in os.walk(root):
             rel_root = os.path.relpath(current, root)
             directory = "" if rel_root == "." else rel_root.replace(os.sep, "/")
@@ -1974,8 +1980,13 @@ def _iter_gallery_files(root, group_runs=True):
                 if kind is None:
                     continue
                 relative_name = name if not directory else f"{directory}/{name}"
-                folder = strip_run_id(relative_name) if group_runs else directory
-                yield relative_name, folder, kind, os.path.join(current, name)
+                if group_runs:
+                    folder, _run_id, subfolder = split_run_path(relative_name)
+                else:
+                    folder, subfolder = directory, ""
+                yield relative_name, folder, subfolder, kind, os.path.join(
+                    current, name
+                )
 
     def _gallery_entries(root, ws):
         entries = []
@@ -1983,19 +1994,24 @@ def _gallery_entries(root, ws):
             files = list(_iter_gallery_files(root))
         except OSError:
             files = []
-        for relative_name, folder, kind, path in files:
+        for relative_name, folder, subfolder, kind, path in files:
             try:
                 stat = os.stat(path)
             except OSError:
                 continue
-            # File names look like '{workflow}-{step}.{i}-{j}.{k}.ext'; the
-            # part before the first dot is a readable label and embedded
-            # metadata carries the precise identity
-            label = os.path.basename(relative_name).split(".")[0]
+            # File names look like '{workflow}-{step}-{i}.{j}.{k}.ext'; every
+            # artifact from one step shares the '{workflow}-{step}' prefix, so
+            # the label keeps the full name including the extension rather
+            # than truncating at the first dot - otherwise sibling outputs of
+            # the same step would show identical, indistinguishable labels,
+            # and a step that writes more than one kind of file (e.g. a still
+            # plus a video) would lose the extension that tells them apart
+            label = os.path.basename(relative_name)
             entries.append(
                 {
                     "name": relative_name,
                     "folder": folder,
+                    "subfolder": subfolder,
                     # Quoted (slashes kept literal): a name carrying '#', '?'
                     # or '%' would otherwise break the src the gallery
                     # renders it into. The mtime still rides along for cache
@@ -2020,6 +2036,7 @@ def gallery(
         limit: int = 200,
         offset: int = 0,
         folder: Optional[str] = None,
+        subfolder: Optional[str] = None,
         ws: Workspace = Depends(selected_workspace),
     ):
         """A page of media files in the output directory, newest first.
@@ -2029,11 +2046,18 @@ def gallery(
         this page), for the UI's folder filter - a run id is not a folder of
         its own, so a workflow's runs group together; '' stands for files
         saved directly at the output root, and is itself always a member so
-        that folder-less outputs stay selectable once anything is nested."""
+        that folder-less outputs stay selectable once anything is nested.
+        'subfolders' is the other axis, over the whole directory the same
+        way: the in-run subfolders steps wrote into ('final',
+        'intermediate'), '' for files at a run's root. `folder` and
+        `subfolder` filter independently and intersect when both are given."""
         entries = _gallery_entries(ws.outputs, ws)
         folders = sorted({e["folder"] for e in entries} | {""})
+        subfolders = sorted({e["subfolder"] for e in entries} | {""})
         if folder is not None:
             entries = [e for e in entries if e["folder"] == folder]
+        if subfolder is not None:
+            entries = [e for e in entries if e["subfolder"] == subfolder]
         offset = max(0, offset)
         limit = max(0, limit)
         page = entries[offset : offset + limit]
@@ -2043,6 +2067,7 @@ def gallery(
             "offset": offset,
             "limit": limit,
             "folders": folders,
+            "subfolders": subfolders,
             "workspace": ws.name,
         }
 
@@ -2334,7 +2359,7 @@ def list_assets(ws: Workspace = Depends(selected_workspace)):
                 files = list(_iter_gallery_files(root, group_runs=False))
             except OSError:
                 files = []
-            for relative, folder, kind, path in files:
+            for relative, folder, _subfolder, kind, path in files:
                 # A name in the workspace shadows the same name in an
                 # examples library, exactly as 'asset:' resolution does
                 if relative in seen:
diff --git a/dw/server/jobs.py b/dw/server/jobs.py
index db43f95c..73f2d55d 100644
--- a/dw/server/jobs.py
+++ b/dw/server/jobs.py
@@ -10,7 +10,7 @@
 import copy
 import json
 import queue
-import random
+import secrets
 import sqlite3
 import time
 import uuid
@@ -18,7 +18,7 @@
 import threading
 
 from ..repl_worker import WorkerManager
-from ..workflow import workflow_from_file, workflow_from_definition
+from ..workflow import SEED_BITS, workflow_from_file, workflow_from_definition
 from ..introspection import workflow_argument_warnings
 from ..variables import argument_errors
 from ..security import (
@@ -514,6 +514,7 @@ def __init__(
         self.history = JobHistory(history_path or resolve_path("jobs.sqlite"))
         self.jobs = {}
         self.last_memory = None
+        self.last_memory_at = None
         # Reentrant: cancel() finishes a queued job while holding it, and
         # _finish's terminal-job trim needs it again on the same thread
         self._lock = threading.RLock()  # guards job state transitions
@@ -773,11 +774,9 @@ def rerun(self, job_id, new_seed=False):
                     "a rerun cannot change it. A workflow with no seed at all "
                     "already draws a fresh one every run."
                 )
-            # Bounded to 53 bits rather than the 64 torch allows: this number
-            # goes out as JSON and comes back through a browser, where every
-            # integer is a double, and a seed that changed on the way through
-            # would be a seed nobody can reproduce
-            arguments = {**arguments, variable: random.getrandbits(53)}
+            # Bounded so the number survives its trip through a browser as
+            # JSON - see SEED_BITS
+            arguments = {**arguments, variable: secrets.randbits(SEED_BITS)}
 
         workspace = spec.get("workspace")
         if (
@@ -1053,7 +1052,7 @@ def _consume_results(self, job):
                 text = message.get("message") or message.get("workflow_name", "")
                 job.add_event({"event": "log", "message": text})
             elif message_type == "memory_info":
-                self.last_memory = message.get("info")
+                self._record_memory(message.get("info"))
                 job.add_event({"event": "memory", "info": self.last_memory})
             elif message_type == "success":
                 self._record_manifest(job, message)
@@ -1106,17 +1105,45 @@ def restart_worker_if_idle(self):
 
     # ---------------------------------------------------------------- memory
 
+    def _record_memory(self, info):
+        """Remember a reading and when it was taken, so a later cached answer
+        can say how old it is."""
+        self.last_memory = info
+        self.last_memory_at = time.time() if info is not None else None
+
+    def _cached_memory(self, reason):
+        """The last reading, labelled with why it is not a live one. A caller
+        comparing two readings must compare only `live: true` ones - a cached
+        `info` was taken at another moment, and while a job loads a model it
+        understates what is resident by however much has loaded since."""
+        info = self.last_memory
+        age = None
+        if info is not None and self.last_memory_at is not None:
+            age = round(time.time() - self.last_memory_at, 1)
+        return {
+            "live": False,
+            "info": info,
+            "stale": info is not None,
+            "reason": reason,
+            "age_seconds": age,
+        }
+
     def memory_status(self, timeout=5):
         """Live memory stats when the worker is idle; the run's last report
         while it is busy. The lock acquire is bounded: the runner holds
         _worker_lock for a job's whole duration, and a poll that raced a job
-        start must fall back to the cached reading, not block for hours."""
+        start must fall back to the cached reading, not block for hours.
+
+        `live` says whether `info` was measured by this call. `stale` and
+        `reason` say why it was not, and `age_seconds` how old the cached
+        reading is; `info` is null when there has never been a reading, which
+        means nothing is resident rather than that the answer is unknown."""
         if self._current_job_id is not None:
-            return {"live": False, "info": self.last_memory}
+            return self._cached_memory("job_running")
         if not self.worker_manager.worker_active:
-            return {"live": False, "info": self.last_memory}
+            return self._cached_memory("worker_stopped")
         if not self._worker_lock.acquire(timeout=2):
-            return {"live": False, "info": self.last_memory}
+            return self._cached_memory("worker_busy")
         try:
             self.worker_manager.send_command({"type": "memory_status"})
             result = self.worker_manager.get_result(timeout=timeout)
@@ -1132,10 +1159,16 @@ def memory_status(self, timeout=5):
                 # so a worker that is merely slow to reply keeps its state -
                 # a timeout is not evidence of death
                 self.worker_manager.mark_crashed()
-            return {"live": False, "info": self.last_memory}
+            return self._cached_memory("worker_unreachable")
         finally:
             self._worker_lock.release()
         if result.get("type") == "memory_status":
-            self.last_memory = result.get("info")
-            return {"live": True, "info": self.last_memory}
-        return {"live": False, "info": self.last_memory}
+            self._record_memory(result.get("info"))
+            return {
+                "live": True,
+                "info": self.last_memory,
+                "stale": False,
+                "reason": None,
+                "age_seconds": 0.0,
+            }
+        return self._cached_memory("worker_unreachable")
diff --git a/dw/subfolders.py b/dw/subfolders.py
new file mode 100644
index 00000000..08de0f53
--- /dev/null
+++ b/dw/subfolders.py
@@ -0,0 +1,107 @@
+"""A step's result 'subfolder': where under the run directory its files go.
+
+A run writes everything into one directory, so a finished episode sits
+beside the twenty scratch files that went into it, distinguished only by
+the step name in each file name. 'subfolder' on a step's result block puts
+that step's files into a subfolder of the run directory instead - by
+convention 'final' or 'intermediate', though the engine treats no name
+specially. Nothing else about placement changes: a step without one writes
+where it always did.
+
+This module owns the shape check and the static pass over an expanded
+definition. Containment - that the joined path really is inside the run
+directory - is the engine's, at the moment it joins (see
+Workflow.step_output_dir).
+"""
+
+from .for_each import MEMBER_SEPARATOR, render_path
+from .security import (
+    InvalidInputError,
+    validate_file_base_name,
+    validate_subfolder,
+)
+
+SUBFOLDER_KEY = "subfolder"
+FILE_BASE_NAME_KEY = "file_base_name"
+
+# Reference prefixes substitution resolves before this pass runs. One still
+# spelled out here is one nothing resolved, and that is the undeclared-
+# variable pass's complaint rather than a shape error
+_UNRESOLVED_PREFIXES = ("variable:", "item:")
+
+
+def step_subfolder(step_definition):
+    """The validated subfolder a step's result names, or '' when it names
+    none.
+
+    Raises:
+        InvalidInputError: If the value is not a string or not a valid
+            subfolder
+    """
+    result = step_definition.get("result")
+    if not isinstance(result, dict) or SUBFOLDER_KEY not in result:
+        return ""
+    value = result[SUBFOLDER_KEY]
+    if not isinstance(value, str):
+        raise InvalidInputError(
+            f"Invalid subfolder: {value!r} - a subfolder is a string like 'final'"
+        )
+    return validate_subfolder(value)
+
+
+def subfolder_errors(workflow_definition, source_indices=None):
+    """Every result 'subfolder' or 'file_base_name' that cannot be written,
+    as [{path, message}].
+
+    The definition handed here has already been substituted and expanded,
+    so every value in it is literal; a 'variable:' or 'item:' still spelled
+    out is left alone. `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")
+        if not isinstance(result, dict):
+            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 ""
+        )
+        for key, check in (
+            (SUBFOLDER_KEY, validate_subfolder),
+            (FILE_BASE_NAME_KEY, validate_file_base_name),
+        ):
+            if key not in result:
+                continue
+            value = result[key]
+            if isinstance(value, str) and value.startswith(_UNRESOLVED_PREFIXES):
+                continue
+            try:
+                if not isinstance(value, str):
+                    raise InvalidInputError(
+                        f"Invalid {key}: {value!r} - expected a string"
+                    )
+                check(value)
+            except InvalidInputError as e:
+                errors.append(
+                    {
+                        "path": render_path(("steps", source, "result", key)),
+                        "message": f"{e}{where}",
+                    }
+                )
+    return errors
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index 946317e5..42ce9a09 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -562,6 +562,106 @@ def loop_audio(
     return _as_track(bed[:, :length], sample_rate)
 
 
+# Shots generated independently land at whatever level the model chose, and
+# joining two of them butts one loudness against another - the one seam
+# artifact no fade can hide, because it is not at the seam, it is either side
+# of it. These are the levels a matched join targets, and the spread at which
+# an unmatched one is worth warning about
+MATCH_MEASURES = ("peak", "rms")
+DEFAULT_MATCH_DBFS = {"peak": -1.0, "rms": -20.0}
+# Matching to an rms target can ask for a gain that would clip; the peak is
+# held here instead, which keeps a loud shot's relative level honest rather
+# than squaring off its transients
+MATCH_CEILING_DBFS = -0.5
+LEVEL_SPREAD_WARN_DB = 6.0
+
+
+def level_dbfs(waveform, measure="peak"):
+    """A waveform's level in dBFS, measured as `peak` or `rms`.
+
+    `rms` is the same measurement `get_gallery_metadata` reports as
+    `mean_dbfs`, so a matched join can be checked against what the gallery
+    said about the shots going into it. A silent track has no level: None.
+    """
+    if measure not in MATCH_MEASURES:
+        raise ValueError(
+            f"level measure must be one of {MATCH_MEASURES}, got '{measure}'"
+        )
+    if waveform is None or waveform.size == 0:
+        return None
+    if measure == "peak":
+        value = float(numpy.abs(waveform).max())
+    else:
+        value = float(numpy.sqrt(numpy.mean(numpy.square(waveform, dtype=numpy.float64))))
+    if value <= 0.0:
+        return None
+    return 20.0 * numpy.log10(value)
+
+
+def match_levels(waveforms, measure, target_dbfs=None, command="concat_videos"):
+    """Scale each waveform so its level sits at one shared target.
+
+    Returns a new list in the same order and shape; a None entry (a video
+    with no soundtrack) and a silent track pass through untouched, since
+    neither has a level to move. A gain that would push the peak past
+    MATCH_CEILING_DBFS is held there and said so in the log - the shot is
+    then quieter than the target rather than clipped.
+    """
+    if measure not in MATCH_MEASURES:
+        raise ValueError(
+            f"{command} 'match_levels' must be one of {MATCH_MEASURES}, "
+            f"got '{measure}'"
+        )
+    if target_dbfs is None:
+        target_dbfs = DEFAULT_MATCH_DBFS[measure]
+    if target_dbfs > 0:
+        raise ValueError(
+            f"{command} 'match_levels_dbfs' cannot be above full scale (0)"
+        )
+
+    matched = []
+    for index, waveform in enumerate(waveforms):
+        level = level_dbfs(waveform, measure)
+        if level is None:
+            matched.append(waveform)
+            continue
+        gain_db = target_dbfs - level
+        peak = level_dbfs(waveform, "peak")
+        if peak is not None and peak + gain_db > MATCH_CEILING_DBFS:
+            held = MATCH_CEILING_DBFS - peak
+            logger.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"
+            )
+            gain_db = held
+        logger.debug(
+            f"{command}: video {index + 1} {measure} {level:.1f} dBFS, "
+            f"gain {gain_db:+.1f} dB"
+        )
+        matched.append((waveform * (10 ** (gain_db / 20.0))).astype(numpy.float32))
+    return matched
+
+
+def warn_on_level_spread(waveforms, command="concat_videos", measure="rms"):
+    """Say something when shots about to be joined are levels apart.
+
+    Independently generated shots drift by 10 dB and more, and each one reads
+    as fine on its own - it is only wrong relative to what it is cut against,
+    and nothing else compares them.
+    """
+    levels = [level for level in (level_dbfs(w, measure) for w in waveforms) if level]
+    if len(levels) < 2:
+        return None
+    spread = max(levels) - min(levels)
+    if spread >= LEVEL_SPREAD_WARN_DB:
+        logger.warning(
+            f"{command}: the tracks being joined span {spread:.1f} dB "
+            f"({measure} {min(levels):.1f} to {max(levels):.1f} dBFS) - the cut "
+            f"will be audible as a level jump. Pass match_levels to even them out"
+        )
+    return spread
+
+
 def _equal_power_ramps(window):
     """Cosine/sine fade curves that sum to constant power across the window."""
     theta = numpy.linspace(0.0, numpy.pi / 2.0, window, endpoint=False)
diff --git a/dw/tasks/concat_videos.py b/dw/tasks/concat_videos.py
index a5bae35d..691487e7 100644
--- a/dw/tasks/concat_videos.py
+++ b/dw/tasks/concat_videos.py
@@ -16,6 +16,8 @@
     bleed_join,
     equal_power_crossfade_join,
     frames_to_samples,
+    match_levels as match_track_levels,
+    warn_on_level_spread,
 )
 from .video_utils import check_same_frame_size, frames_as_pil_list, load_audio_video
 
@@ -29,6 +31,8 @@ def concat_videos(
     audio_bleed_ms=0,
     seam_fade_ms=None,
     fps=None,
+    match_levels=None,
+    match_levels_dbfs=None,
 ):
     """Concatenate a list of videos into a single AudioVideo.
 
@@ -58,6 +62,18 @@ def concat_videos(
             the wrong tool for a continuous bed such as a laugh track or room
             tone: a fade only deepens the hole a bleed is there to cover
         fps: Frame rate of the videos - required to join audio when trimming
+        match_levels: Even the shots' loudness out before joining -
+            "rms" matches perceived level (the measurement
+            get_gallery_metadata reports as mean_dbfs), "peak" matches the
+            loudest sample. Off by default. Shots generated independently
+            land 10 dB apart routinely, and that jump is the one seam
+            artifact none of the fade controls can hide, because it is not
+            at the seam but either side of it. 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". A shot
+            that would clip at the target is held just below full scale
+            instead
 
     Returns:
         One AudioVideo; its audio is None when no input video carries any
@@ -71,6 +87,20 @@ def concat_videos(
     clips = [frames_as_pil_list(v) for v in videos]
     check_same_frame_size(clips, "concat_videos")
 
+    # Every track up front rather than one at a time: levels are matched
+    # across the whole set, so the last shot's loudness has to be known
+    # before the first one is scaled
+    waveforms = [
+        as_channels_samples(video.audio)
+        if isinstance(video, AudioVideo) and video.audio is not None
+        else None
+        for video in videos
+    ]
+    if match_levels:
+        waveforms = match_track_levels(waveforms, match_levels, match_levels_dbfs)
+    else:
+        warn_on_level_spread(waveforms)
+
     frames = []
     audio = None
     sample_rate = None
@@ -79,10 +109,10 @@ def concat_videos(
         head_trim = trim_frames if index > 0 else 0
         frames.extend(clip[head_trim:])
 
-        if not isinstance(video, AudioVideo) or video.audio is None:
+        if waveforms[index] is None:
             continue
 
-        waveform = as_channels_samples(video.audio)
+        waveform = waveforms[index]
         if audio is None:
             audio, sample_rate = waveform, video.sample_rate
             continue
diff --git a/dw/tasks/dissolve_videos.py b/dw/tasks/dissolve_videos.py
index 5e57a052..66841afd 100644
--- a/dw/tasks/dissolve_videos.py
+++ b/dw/tasks/dissolve_videos.py
@@ -18,7 +18,12 @@
 from PIL import Image
 
 from ..result import AudioVideo
-from .audio_utils import as_channels_samples, crossfade_concat
+from .audio_utils import (
+    as_channels_samples,
+    crossfade_concat,
+    match_levels as match_track_levels,
+    warn_on_level_spread,
+)
 from .video_utils import check_same_frame_size, frames_as_array, load_audio_video
 
 logger = logging.getLogger("dw")
@@ -31,6 +36,8 @@ def dissolve_videos(
     fade_out_frames=0,
     fade_color=(0, 0, 0),
     fps=None,
+    match_levels=None,
+    match_levels_dbfs=None,
 ):
     """Task command: join videos with cross-dissolves at every seam.
 
@@ -45,6 +52,12 @@ def dissolve_videos(
         fade_color: The RGB colour the fades come from and go to
         fps: Frame rate of the videos - required to crossfade audio at a
             dissolve, and ignored when no video carries any
+        match_levels: Even the shots' loudness out before joining - "rms"
+            for perceived level, "peak" for the loudest sample. Off by
+            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"
 
     Returns:
         One AudioVideo; its audio is None unless every input carries a track
@@ -88,7 +101,9 @@ def dissolve_videos(
             )
 
     frames = [Image.fromarray(frame) for frame in joined.round().astype(numpy.uint8)]
-    audio, sample_rate = _dissolve_audio(loaded, dissolve_frames, fps)
+    audio, sample_rate = _dissolve_audio(
+        loaded, dissolve_frames, fps, match_levels, match_levels_dbfs
+    )
     logger.info(
         f"Dissolved {len(clips)} videos into {len(frames)} frames "
         f"({dissolve_frames}-frame seams)"
@@ -118,7 +133,9 @@ def _blend(from_frames, to_frames, weights):
     return from_frames * (1 - weights) + to_frames * weights
 
 
-def _dissolve_audio(videos, dissolve_frames, fps):
+def _dissolve_audio(
+    videos, dissolve_frames, fps, match_levels=None, match_levels_dbfs=None
+):
     """Crossfade every video's track over the seams' own span."""
     tracks = [v for v in videos if isinstance(v, AudioVideo) and v.audio is not None]
     if len(tracks) != len(videos):
@@ -136,4 +153,10 @@ def _dissolve_audio(videos, dissolve_frames, fps):
     sample_rate = rates.pop()
     crossfade_ms = dissolve_frames / fps * 1000 if dissolve_frames else 0
     waveforms = [as_channels_samples(v.audio) for v in tracks]
+    if match_levels:
+        waveforms = match_track_levels(
+            waveforms, match_levels, match_levels_dbfs, "dissolve_videos"
+        )
+    else:
+        warn_on_level_spread(waveforms, "dissolve_videos")
     return crossfade_concat(waveforms, sample_rate, crossfade_ms), sample_rate
diff --git a/dw/worker.py b/dw/worker.py
index 911aeb8e..1877ecde 100644
--- a/dw/worker.py
+++ b/dw/worker.py
@@ -22,6 +22,7 @@
 from dw.security import validate_output_path
 from dw.events import RunContext, WorkflowCancelled
 from dw import get_device_type, empty_device_cache, device_memory_stats
+from dw.host_memory import host_memory_fields
 
 logger = logging.getLogger("dw.worker")
 
@@ -177,6 +178,9 @@ def _handle_execute(self, command: Dict[str, Any]):
         # whatever the run had written by then - the steps that did complete
         # are the first thing a failed long run is asked about
         workflow = None
+        # Bound for the same reason: the failure path evicts against what the
+        # run touched, and a run can fail before it has a context at all
+        context = None
 
         try:
             set_log_level(log_level)
@@ -232,12 +236,7 @@ def _handle_execute(self, command: Dict[str, Any]):
                 if asset_token is not None:
                     deactivate_asset_dir(asset_token)
 
-            # Drop cached pipelines this run no longer touched - an edited
-            # workflow that removed or redefined a step leaves those behind
-            for cache_key in list(self.loaded_pipelines):
-                if cache_key not in context.touched_pipelines:
-                    logger.info("Evicting cached pipeline no longer in workflow")
-                    del self.loaded_pipelines[cache_key]
+            self._evict_untouched_pipelines(context)
 
             self.run_count += 1
 
@@ -268,17 +267,28 @@ def _handle_execute(self, command: Dict[str, Any]):
             )
         except Exception as e:
             logger.error(f"Error executing workflow: {e}", exc_info=True)
-            self.result_queue.put(
-                {
-                    "type": "error",
-                    "message": f"Workflow execution error: {str(e)}",
-                    "traceback": traceback.format_exc(),
-                    # The files the steps before the failure wrote are on
-                    # disk; reporting them is what keeps a run that died at
-                    # step five from looking like one that produced nothing
-                    "manifest": getattr(workflow, "manifest", []),
-                }
-            )
+            failure = {
+                "type": "error",
+                "message": f"Workflow execution error: {str(e)}",
+                "traceback": traceback.format_exc(),
+                # The files the steps before the failure wrote are on
+                # disk; reporting them is what keeps a run that died at
+                # step five from looking like one that produced nothing
+                "manifest": getattr(workflow, "manifest", []),
+            }
+            # The exception's traceback reaches every frame between here and
+            # the failure, and those frames hold whatever a half-finished load
+            # had built - so a collection that runs while the exception is
+            # still live frees none of it. The report above is a formatted
+            # string by now, so nothing is lost by letting the traceback go
+            e.__traceback__ = None
+            del e
+            # Success and cancellation both reclaim; failure did neither, so a
+            # half-loaded pipeline and any variant the attempt superseded
+            # stayed resident and the next attempt loaded on top of them
+            self._evict_untouched_pipelines(context)
+            self._cleanup_between_runs()
+            self.result_queue.put(failure)
 
     def _load_workflow(self, command: Dict[str, Any], output_dir: str):
         """Build the Workflow a command names, and its cache identity."""
@@ -363,6 +373,22 @@ def _handle_memory_status(self):
         memory_info = self._get_memory_info()
         self.result_queue.put({"type": "memory_status", "info": memory_info})
 
+    def _evict_untouched_pipelines(self, context):
+        """Drop cached pipelines this run no longer touched.
+
+        An edited workflow that removed or redefined a step leaves those
+        behind, and so does a failed attempt whose superseded variant nothing
+        will ever load again. A run that failed before it had a context
+        touched nothing this can be judged against, so nothing is dropped -
+        the caller's own cleanup still runs.
+        """
+        if context is None:
+            return
+        for cache_key in list(self.loaded_pipelines):
+            if cache_key not in context.touched_pipelines:
+                logger.info("Evicting cached pipeline no longer in workflow")
+                del self.loaded_pipelines[cache_key]
+
     def _cleanup_between_runs(self):
         """
         Aggressive memory cleanup between workflow runs.
@@ -487,6 +513,13 @@ def _get_memory_info(self) -> Dict[str, Any]:
             "gpu_device_name": None,
         }
 
+        # Host memory beside the device figures: the offloading these
+        # workflows use keeps weights in RAM by design, so a leak - or a run
+        # that simply has not let go of a model - shows here and nowhere
+        # else. Measured inside the worker, so the process figures are the
+        # worker's own
+        info.update(host_memory_fields())
+
         try:
             stats = device_memory_stats()
             info["gpu_available"] = stats["available"]
diff --git a/dw/workflow.py b/dw/workflow.py
index 48399ea0..00b898a3 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -6,6 +6,7 @@
 import gc
 import hashlib
 import logging
+import secrets
 from datetime import datetime, timezone
 from .arguments import (
     realize_args,
@@ -26,6 +27,7 @@
     StepResults,
     previous_result_reference_errors,
 )
+from .subfolders import step_subfolder, subfolder_errors
 from .step import Step
 from .step_cache import (
     step_cache,
@@ -60,7 +62,7 @@
 from .pipeline_processors.pipeline import Pipeline
 from .tasks.model_cache import clear_model_cache
 from .tasks.task import Task
-from . import get_device, empty_device_cache
+from . import get_device, empty_device_cache, device_memory_stats
 from .security import (
     validate_path,
     validate_workflow_path,
@@ -74,6 +76,10 @@
 
 logger = logging.getLogger("dw")
 
+# The widest integer JavaScript's double represents exactly - the ceiling on
+# any seed the engine draws, since seeds travel as JSON through a browser
+SEED_BITS = 53
+
 
 class ConstantError(ValueError):
     """A 'constant:' variable default that failed to resolve during
@@ -212,6 +218,17 @@ def pipeline_cache_key(pipeline_definition):
     return hashlib.sha256(serialized.encode()).hexdigest()
 
 
+def _allocated_mb():
+    """Device memory in use right now, for the pipeline_released event -
+    None where the backend cannot say, so a reading is never confused with
+    a genuine zero."""
+    try:
+        stats = device_memory_stats()
+    except Exception:  # a progress figure is never worth failing a run over
+        return None
+    return stats["allocated_mb"] if stats["available"] else None
+
+
 def release_unreferenced_results(results, remaining_refs):
     """Drop results no remaining reference can resolve to.
 
@@ -306,6 +323,26 @@ def effective_output_dir(self):
             os.path.join(self.output_dir, subfolder) if subfolder else self.output_dir
         )
 
+    def step_output_dir(self, step_definition):
+        """Where one step writes: the run directory, or the subfolder of it
+        the step's result names.
+
+        Computed here, once, rather than inside Result.save, because two
+        things write on a step's behalf - Result.save for its results and
+        the pipeline wrapper for a chain's save_segments spill - and both
+        have to land in the same place. The shape was checked statically by
+        validation_errors; it is checked again here for a definition that
+        reached the engine without it, and containment (that the joined
+        path is really inside the run directory) is checked on the join.
+        """
+        base = self.effective_output_dir
+        subfolder = step_subfolder(step_definition)
+        if not subfolder:
+            return base
+        target = validate_output_path(os.path.join(base, subfolder), base)
+        os.makedirs(target, exist_ok=True)
+        return target
+
     def expanded_definition(self, arguments=None, source_indices=None):
         """The definition as the run will see it: constants realized,
         variables substituted - the caller's `arguments` folded in when they
@@ -378,7 +415,9 @@ def validation_errors(self, arguments=None):
             # reported against 'variables' as a whole rather than escaping
             # as an unhandled exception
             return [{"path": "variables", "message": str(e)}]
-        return previous_result_reference_errors(expanded, source_indices)
+        return previous_result_reference_errors(
+            expanded, source_indices
+        ) + subfolder_errors(expanded, source_indices)
 
     def _undeclared_variable_errors(self, arguments=None):
         """Every 'variable:' reference naming nothing the workflow declares.
@@ -550,9 +589,14 @@ def run(
             # while its seed still changes every run
             self._cache_enabled_this_run = cache_enabled_this_run
             if default_seed is None:
-                # A fresh generator draws a random seed without touching the
-                # global RNG the process may have seeded for reproducibility
-                default_seed = torch.Generator().seed()
+                # OS entropy rather than torch or random, so a process that
+                # seeded either for reproducibility is not disturbed. Bounded
+                # to 53 bits rather than the 64 torch allows: the seed is
+                # embedded in the image, the manifest and the realized
+                # workflow as JSON, and a browser reads every integer as a
+                # double - a seed that changed on the way through would be a
+                # seed nobody can reproduce
+                default_seed = secrets.randbits(SEED_BITS)
             workflow_def["seed"] = default_seed
             resolved_seed = default_seed
 
@@ -740,8 +784,55 @@ def run(
                     hits_this_run.add(step.name)
                 else:
                     result = step.run(results, pipelines, step_action)
+
+                # A sub-workflow's saves land in the child's manifest - read it
+                # here, before the release below may drop the child
+                sub_manifest = (
+                    list(getattr(step_action, "manifest", []))
+                    if isinstance(step_action, Workflow)
+                    else []
+                )
+
+                # A released pipeline frees its memory for later steps - the
+                # alternative on a card that cannot hold two models is offloading
+                # everything, which taxes every run to survive one transition.
+                # Before the write, not after: the result is already in host
+                # memory and saving never touches the pipeline, so a release
+                # that waited for the write would hold ~10 GB on the device
+                # through the longest phase of a video step. The loop's own
+                # locals are the last references to this step's action, so
+                # clearing that is part of the release - a popped pipeline this
+                # frame still holds is not freed, and it would otherwise stay
+                # resident through the next step's load, which is exactly when
+                # both models would be in memory at once
+                if step_data.get("release_pipeline", False):
+                    logger.info(f"Releasing pipeline for step: {step.name}")
+                    before = _allocated_mb()
+                    pipelines.pop(self._pipeline_keys_by_step.get(step.name), None)
+                    step_action = None
+                    gc.collect()
+                    empty_device_cache()
+                    # Say so on the event stream. The release is otherwise
+                    # invisible to a consumer: it sits inside the sub-second
+                    # window between a step's generation and its files
+                    # appearing, which is too narrow to catch by polling
+                    # get_memory, and it is exactly the ordering this event
+                    # exists to make readable (it precedes the step's
+                    # step_end, and on a released card the figures show the
+                    # drop rather than implying it)
+                    run_context.emit(
+                        "pipeline_released",
+                        workflow=workflow_id,
+                        step=step.name,
+                        index=i,
+                        gpu_memory_allocated_mb=_allocated_mb(),
+                        gpu_memory_allocated_before_mb=before,
+                    )
+
+                if not reused:
                     saved_files = result.save(
-                        self.effective_output_dir, f"{workflow_id}-{step.name}.{i}"
+                        self.step_output_dir(step_data),
+                        f"{workflow_id}-{step.name}.{i}",
                     )
                     if is_cacheable:
                         step_cache.put(
@@ -758,15 +849,19 @@ def run(
                 # 'reused' marks files an earlier run wrote and this one only
                 # republished, so nothing downstream (job_for_file, the
                 # gallery) credits this run with writing them
-                manifest_entry = {"step": step.name, "files": saved_files}
+                subfolder = step_subfolder(step_data)
+                manifest_entry = {
+                    "step": step.name,
+                    "files": saved_files,
+                    "subfolder": subfolder,
+                }
                 if reused:
                     manifest_entry["reused"] = True
                 self.manifest.append(manifest_entry)
-                # A sub-workflow's saves land in the child's manifest - roll
-                # them up so job history and the gallery see every file
-                if isinstance(step_action, Workflow):
-                    self.manifest.extend(getattr(step_action, "manifest", []))
-                step_end_data = {"files": saved_files}
+                # roll the child's saves up so job history and the gallery see
+                # every file
+                self.manifest.extend(sub_manifest)
+                step_end_data = {"files": saved_files, "subfolder": subfolder}
                 if reused:
                     step_end_data["reused"] = True
                 run_context.emit(
@@ -783,17 +878,9 @@ def run(
                 # already, and last_result keeps the workflow's return value
                 release_unreferenced_results(results, remaining_refs)
 
-                # A released pipeline frees its memory for later steps - the
-                # alternative on a card that cannot hold two models is offloading
-                # everything, which taxes every run to survive one transition
-                if step_data.get("release_pipeline", False):
-                    logger.info(f"Releasing pipeline for step: {step.name}")
-                    pipelines.pop(self._pipeline_keys_by_step.get(step.name), None)
-
                 # The loop's own locals are the last references to this step's
-                # action and result - a released pipeline would otherwise stay
-                # resident through the next step's load, which is exactly when
-                # both models would be in memory at once
+                # action and result - anything they still hold would stay
+                # resident through the next step's load
                 step_action = None
                 result = None
 
@@ -959,7 +1046,7 @@ def create_step_action(
                     default_seed,
                     device,
                     cached_pipeline.pipeline,  # Reuse the actual loaded model
-                    output_dir=self.effective_output_dir,
+                    output_dir=self.step_output_dir(step_definition),
                     file_prefix=self.step_file_prefix(step_name),
                 )
                 # Set up generator with potentially new seed. no_generator is a
@@ -1000,7 +1087,7 @@ def create_step_action(
                 step_definition["pipeline"],
                 default_seed,
                 device,
-                output_dir=self.effective_output_dir,
+                output_dir=self.step_output_dir(step_definition),
                 file_prefix=self.step_file_prefix(step_name),
             )
             # Loading is the longest silence in a run: weights, quantization,
@@ -1029,7 +1116,7 @@ def create_step_action(
                 default_seed,
                 device,
                 previous_pipeline.pipeline,
-                output_dir=self.effective_output_dir,
+                output_dir=self.step_output_dir(step_definition),
                 file_prefix=self.step_file_prefix(step_definition["name"]),
             )
 
diff --git a/dw/workflow_schema.json b/dw/workflow_schema.json
index 1990e06a..3cefb295 100644
--- a/dw/workflow_schema.json
+++ b/dw/workflow_schema.json
@@ -719,9 +719,11 @@
                     "type": "object",
                     "properties": {
                         "enable_slicing": {
+                            "description": "Decode the latent batch one sample at a time rather than all at once - the answer to a decode that runs out of memory on a batch the denoise itself fitted. Costs nothing but the loss of batched decode parallelism.",
                             "type": "boolean"
                         },
                         "enable_tiling": {
+                            "description": "Decode in tiles rather than in one allocation, for a single sample too large to decode whole - a long or high-resolution video, where the peak is the decode rather than the denoise. Combines with 'enable_slicing'.",
                             "type": "boolean"
                         },
                         "channels_last": {
@@ -1109,7 +1111,11 @@
                     "default": true
                 },
                 "file_base_name": {
-                    "description": "The base name for saving result and metadata files. The file extension is determined by context and content_type.",
+                    "description": "The base name for saving result and metadata files. A name, not a path - it may not contain a separator; to place a step's files in a subfolder of the run directory set 'subfolder'. The file extension is determined by context and content_type.",
+                    "type": "string"
+                },
+                "subfolder": {
+                    "description": "A subfolder of the run directory this step's files are written into, as a relative path like 'final' or 'shots/act-1'. Optional: without it the files land at the root of the run directory as they always have. By convention a step whose output the user will be shown is 'final' and everything else is 'intermediate', which is how a consumer tells the deliverable from the scratch files without knowing the workflow; the engine treats no name specially. May be a 'variable:' or, inside a for_each step, an 'item:' reference. Each segment must start with a letter, digit or underscore; '..' and '\\' are refused.",
                     "type": "string"
                 },
                 "fps": {
diff --git a/dw_mcp/catalog.py b/dw_mcp/catalog.py
index 6582cfd1..27997f13 100644
--- a/dw_mcp/catalog.py
+++ b/dw_mcp/catalog.py
@@ -137,9 +137,14 @@ def list_jobs(client, limit=20, status=None, workspace=None):
     return answer
 
 
-def list_gallery(client, limit=50):
-    """Generated media in the output directory, newest first."""
-    return client.get_json("/api/gallery", params={"limit": limit})
+def list_gallery(client, limit=50, subfolder=None):
+    """Generated media in the output directory, newest first. `subfolder`
+    narrows to one in-run subfolder ('final', 'intermediate', '' for files
+    at a run's root); None means every file."""
+    params = {"limit": limit}
+    if subfolder is not None:
+        params["subfolder"] = subfolder
+    return client.get_json("/api/gallery", params=params)
 
 
 def get_gallery_metadata(client, name, envelope=False):
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 4e423746..a1c861de 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -256,7 +256,28 @@ def list_models() -> dict:
 
     def get_memory() -> dict:
         """Get the worker's VRAM and RAM statistics. Check this first when a
-        job fails with an out-of-memory error."""
+        job fails with an out-of-memory error.
+
+        `gpu_*` is the card, `host_memory_*` the machine:
+        `host_memory_rss_mb` is what the worker process holds and
+        `host_memory_peak_rss_mb` the most it has ever held, beside the
+        machine's `host_memory_total_mb` / `host_memory_available_mb`. Read
+        both - a workflow that offloads (`offload: "sequential"`,
+        `group_offload`) keeps its weights in host memory by design, so the
+        card can sit near-empty through a generation and VRAM alone will not
+        show what a run is holding or failing to release. A host field is
+        absent, rather than null, on a platform that cannot measure it.
+
+        `live: true` means `info` was measured now and is the worker's own
+        memory - only these readings are comparable with each other.
+        `live: false` means it was not: `info: null` (with `stale: false`)
+        means nothing has been measured because nothing is resident, and a
+        populated `info` is a cached earlier reading - `reason` says why
+        (`job_running`, `worker_stopped`, `worker_busy`, `worker_unreachable`)
+        and `age_seconds` how old it is. A cached reading is not this
+        moment's: one taken while a job is loading a model understates what
+        is resident by however much has loaded since, so ask again when the
+        server is idle rather than comparing it against a live figure."""
         return catalog.get_memory(client)
 
     def get_health() -> dict:
@@ -297,16 +318,21 @@ def list_jobs(
             client, limit=limit, status=status, workspace=workspace
         )
 
-    def list_gallery(limit: int = 50) -> dict:
+    def list_gallery(limit: int = 50, subfolder: str | None = None) -> dict:
         """List generated output files, newest first. A name is
-        <workflow>/<run id>/<file> - the form `get_output_image`,
-        `get_output_text`, `download_output`, `keep_output` and
-        `delete_output` all take, and the form an "output:" reference in a
-        later workflow is built from. Each entry also carries a ready-made
-        `url` for viewing the file over HTTP, already scoped to the right
-        workspace; use it as given rather than composing one from the
-        name."""
-        return catalog.list_gallery(client, limit=limit)
+        <workflow>/<run id>/<file>, where <file> may itself sit in a
+        subfolder the step chose (`final/episode.mp4`) - the form
+        `get_output_image`, `get_output_text`, `download_output`,
+        `keep_output` and `delete_output` all take, and the form an
+        "output:" reference in a later workflow is built from. Each entry
+        carries `folder` (the workflow) and `subfolder` (the part of the run:
+        by convention `final` is the deliverable and `intermediate` the
+        scratch work, '' when the step chose none); `subfolder=` filters on
+        the latter, so `subfolder="final"` is "what did these runs
+        deliver". Each entry also carries a ready-made `url` for viewing the
+        file over HTTP, already scoped to the right workspace; use it as
+        given rather than composing one from the name."""
+        return catalog.list_gallery(client, limit=limit, subfolder=subfolder)
 
     def get_gallery_metadata(name: str, envelope: bool = False) -> dict:
         """Get the metadata embedded in a generated file: the exact
@@ -565,7 +591,11 @@ def validate_workflow(
         `prompt:` or `output:` reference that names nothing this workspace
         can reach - each with `arguments.<name>` as its path.
         `checked_arguments` lists what was checked, so a valid answer says
-        whether it covered your values or only the stored defaults."""
+        whether it covered your values or only the stored defaults.
+
+        A `result.subfolder` or `file_base_name` that cannot be written (a
+        `..`, a backslash, a separator in `file_base_name`) is reported here
+        at its JSON path, after `for_each` expansion."""
         return authoring.validate_workflow(
             client,
             workflow=workflow,
@@ -581,7 +611,12 @@ def save_workflow(name: str, workflow: dict) -> dict:
         examples directory) is not overwritten - the copy lands in the
         writable directory and shadows it from then on, which is how an
         example gets adapted without being damaged. `name` may include
-        folders."""
+        folders.
+
+        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)
 
     def delete_workflow(name: str) -> dict:
@@ -696,10 +731,13 @@ def run_workflow(
     def get_job(job_id: str) -> dict:
         """Get a job's status, argument warnings, output manifest, error and
         traceback. The manifest names each step's files the way
-        `get_output_image`, `download_output` and `keep_output` take them; a
-        step served from the step cache is marked `reused` and reports the
-        earlier run's files. When a job failed, the error and traceback here
-        are what to read before changing anything."""
+        `get_output_image`, `download_output` and `keep_output` take them,
+        and each entry's `subfolder` says what kind of output the step
+        declared - by convention `final` is the deliverable, `intermediate`
+        the scratch work, and '' a step that said nothing. A step served
+        from the step cache is marked `reused` and reports the earlier run's
+        files. When a job failed, the error and traceback here are what to
+        read before changing anything."""
         return diagnose.get_job(client, job_id)
 
     def get_job_workflow(job_id: str) -> dict:
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index a6b2d017..9fb4f78b 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -13,12 +13,22 @@ Lightricks' own caption spec, quoted below from diffusers.
 ## Before anything
 
 1. `get_server_info`: the device and the workspace. These templates quantize
-   with SDNQ on CUDA; on an `mps` or `cpu` server say so and stop, because
-   none of them fit there.
+   with SDNQ on CUDA; on an `mps` or `cpu` server say so and stop - none of
+   them fit there.
 2. `list_workflows(shape="shot")`: all eight of the family's templates carry
    that shape. Take their current names, `summary`, `traits` and `cost` from
    the listing and trust it over the names quoted below.
 3. `get_workflow` on the one chosen, for its variables and their defaults.
+4. Before anything near the card's ceiling - a full-size refine, 481 frames, a
+   2x upscale - `get_memory` on an idle server and read a `live: true`
+   reading's `gpu_memory_allocated_mb`. Only those are the worker's own and
+   only those compare: `info: null` means nothing is resident, go ahead, and a
+   `live: false` reading with an `info` is cached from another moment - it
+   reads low mid-load, so ask again when the server is idle. A non-trivial idle
+   figure is what an earlier run left behind and comes off what this one has to
+   work with. Nothing over MCP clears it: ask the operator to restart the
+   worker rather than retrying into it, since a failed attempt is itself what
+   leaves weight resident.
 
 ## Which shape is the request
 
@@ -36,14 +46,14 @@ Lightricks' own caption spec, quoted below from diffusers.
   low-resolution pass and has the IC-LoRA re-render it at twice the size,
   inventing detail rather than interpolating. `base_width` and `base_height`
   are that first render's size, `width` and `height` the doubled target; both
-  passes run the same eight distilled sigmas at guidance 1.0. Nothing in this
-  family takes a user-supplied video, so a user's own footage is not a fit for
-  any of these templates.
-- **Longer**: `templates/ltx2/extend-clip` generates an opening and then
-  continues it conditioned on the whole opening, not on a single frame - a
-  supplied clip is not an input here either; `templates/ltx2/chained-segments`
-  re-runs per segment on the previous last frame and stitches. Neither is a Lightricks recipe; both are dw's, and
-  a single 481-frame pass reaches 20 seconds before either is needed.
+  passes run the same eight distilled sigmas at guidance 1.0. No template in
+  this family takes a user-supplied video, so a user's own footage is not a
+  fit for any of them.
+- **Longer**: `templates/ltx2/extend-clip` generates an opening and continues
+  it conditioned on the whole opening, not on a single frame;
+  `templates/ltx2/chained-segments` re-runs per segment on the previous last
+  frame and stitches. Neither is a Lightricks recipe; both are dw's, and a
+  single 481-frame pass reaches 20 seconds before either is needed.
 
 If none fits, compose from `list_tasks` before authoring a new workflow, and
 read the `workflows` guide's authoring section first.
@@ -64,9 +74,9 @@ read the `workflows` guide's authoring section first.
   `STAGE_2_DISTILLED_SIGMA_VALUES` entry) and run its three sigmas at full size.
 - An image condition is re-compressed at CRF 18 to match training and needs a
   PIL image; a multi-frame video condition is not re-compressed.
-- Audio is generated in the first pass; nothing refines it afterwards, so
-  carry the audio latents (two-stage) or pair the soundtrack back
-  (`pair_audio`) on any step that works on frames alone.
+- Audio is generated in the first pass and nothing refines it, so carry the
+  audio latents (two-stage) or pair the soundtrack back (`pair_audio`) on any
+  step that works on frames alone.
 
 ## Prompts
 
@@ -76,9 +86,7 @@ type, a camera motion (say static when there is none) and a viewpoint, with
 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 this spec. For a one-line idea,
-`templates/ltx2/enhance-prompt` runs the model's own enhancer with the same
-spec. The spec itself, from `diffusers.pipelines.ltx2.utils.LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT`
+`prompts/ltx2/` are written to it. The spec itself, 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):
 
@@ -116,37 +124,47 @@ AESTHETIC QUALITY (in addition to the above, without breaking the objective capt
 ## Run and judge
 
 1. `validate_workflow` first - free, and it catches arguments the pipeline
-   does not accept.
+   rejects.
 2. Quote the listing's `cost`. Only `templates/ltx2/text-to-video` and
    `templates/ltx2/two-stage` declare one; for the other six say so and give
    the shape of the spend instead - a 121-frame clip at 960x544 is under a
-   minute warm on a 24 GB card, the two-stage flow about eight, and extend
-   and chain multiply by their passes. Either way get the user's go-ahead
-   before `run_workflow` with `acknowledged_cost=true`.
-3. `wait_for_job`, then `get_job` for the manifest. Writing a 121-frame
-   1536x896 clip takes minutes after the last step ends; the job is not stuck.
-4. You cannot watch a video: no tool returns a frame from one, and this family
+   minute warm on a 24 GB card, the two-stage flow about eight, and extend and
+   chain multiply by their passes. Either way get the go-ahead before
+   `run_workflow` with `acknowledged_cost=true`.
+3. `wait_for_job`, then `get_job` for the manifest. The write-out runs after
+   the last step ends, reports nothing while it does, and is not free: roughly
+   4 s per frame at 1536x896 - about 8 minutes for 121 frames, about half an
+   hour for 481. Scale by frame count from that rate rather than reading
+   "minutes" as a constant, and expect it to fall with the frame size. The job
+   is not stuck.
+4. Every step that writes pays that, so only the ones worth writing should:
+   `"result": {"save": false}` on the rest, as `two-stage` does for `base` and
+   `upscale`. On a long chain it is the largest saving there is, and missing
+   it is silent. What does write carries a `subfolder` in the manifest: the step the user will be
+   shown is `final` and every other saving step `intermediate`, the way
+   `generative-upscale` keeps `upscaled` in `final` and its low-resolution
+   pass in `intermediate` so the two sizes can be compared.
+   `list_gallery(subfolder="final")` then lists only deliverables. Keep both
+   conventions in anything you compose.
+5. You cannot watch a video: no tool returns a frame from one, and this family
    has no image steps for `get_output_image` to read. Hand the user the gallery
-   `url` (`list_gallery`, or the manifest's file name) and ask them to look, and
-   check what you can yourself - `get_job` for the manifest and its warnings,
+   `url` (`list_gallery`, or the manifest's file name), and check what you can
+   yourself - `get_job` for the manifest and its warnings,
    `get_gallery_metadata` for duration, size and whether an audio stream is
-   present. Ask the user to look for the family's failure modes: a scene cut
-   where the prompt contradicted the image; softness where the refine pass was
+   present. Ask them to look for the family's failure modes: a scene cut where
+   the prompt contradicted the image; softness where the refine pass was
    skipped; a near-silent soundtrack where the caption gave the sound nothing
    to do.
-5. After an inline run worth keeping, `get_job_workflow` and `save_workflow` it,
+6. After an inline run worth keeping, `get_job_workflow` and `save_workflow` it,
    so the next run is by name rather than by pasting JSON; `export_job` bundles
    the run — workflow, manifest, job row and media — for git. The bundle is on
    the server: fetch its zip URL and unpack it into `exports/` under the
    session's working directory, never a temp directory, and do not make a
-   folder named after the job id first, since the archive already unpacks
-   into one.
+   job-id folder first - the archive already unpacks into one.
 
 ## Sources
 
 Lightricks/LTX-2.5-Diffusers model card, the `ltx-pipelines` docs and
 CHANGELOG (github.com/Lightricks/LTX-2), the diffusers LTX-2 pipelines and
 `utils.py`. Read 2026-09-07; the audit is
-`docs/proposals/audits/2026-09-07-ltx-2.5-audit.md`. Since 2026-08 Lightricks
-route production quality through their DFR pipeline, which diffusers ships
-and no template here uses yet.
+`docs/proposals/audits/2026-09-07-ltx-2.5-audit.md`.
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index ab620ab0..d5d1672e 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -164,7 +164,10 @@ inherits the portrait's composition.
    by its segment count. Get the user's go-ahead before `run_workflow` with
    `acknowledged_cost=true`.
 3. `wait_for_job`, then `get_job` for the manifest. A cancelled H3 job runs
-   on to its next step boundary, minutes on this model.
+   on to its next step boundary, minutes on this model. Each entry carries
+   `subfolder`: `final` is the deliverable (`episode`, `music_video`,
+   `voyage`), `intermediate` the scratch; keep that split in anything you
+   compose.
 4. You cannot watch a video: no tool returns a frame from one. Hand the user
    the gallery `url` (`list_gallery`, or the manifest's file name) and ask them
    to look, and check what you can yourself - `get_job` for the manifest and
diff --git a/plugins/dw/skills/minimax-music3/SKILL.md b/plugins/dw/skills/minimax-music3/SKILL.md
index b0d5f858..76f5547f 100644
--- a/plugins/dw/skills/minimax-music3/SKILL.md
+++ b/plugins/dw/skills/minimax-music3/SKILL.md
@@ -17,6 +17,19 @@ shapes; do not author a new workflow until the shape decision below fails.
 2. `list_workflows(shape="audio")`, and `shape="sequence"` for the music video.
    Trust the names quoted below only after the listing confirms them.
 3. `get_workflow` on the one chosen, for its variables and their defaults.
+4. Before a long track or the music video - anything that will sit near the
+   card's ceiling - `get_memory` with the server idle and read a `live: true`
+   reading's `gpu_memory_allocated_mb`. Only a live reading is the worker's own
+   and only live readings compare with each other: `info: null` means nothing
+   is resident, go ahead, while a `live: false` reading with a populated `info`
+   is cached from another moment - it reads low while a job is loading a model,
+   so ask again once the server is idle rather than trusting it. A non-trivial
+   idle figure is what an earlier run left behind, and it comes off the ~22 GB
+   these templates need. Nothing over
+   MCP clears it, so say so and ask the operator to restart the worker rather
+   than retrying into it - a failed attempt is itself what leaves weight
+   resident, so an immediate retry starts from less than the attempt that just
+   failed had.
 
 ## Which shape is the request
 
@@ -48,6 +61,15 @@ If none fits, compose from `list_tasks` (`slice_audio`, `fade_audio`,
   the song ends, and generation is cut at the ceiling if it has not. Default
   60 seconds. Ask for more than the piece needs and trim; the run's time
   follows the length actually generated, so the margin is free.
+  The consequence to size by: the arc the caption describes stretches to fill
+  the budget it is given, so a ceiling set at the intended length is not a
+  piece that ends early with room to spare - it is the same piece pulled out
+  to the ceiling and then cut off at it. A caption written for about 20
+  seconds under a 22-second ceiling comes back stretched and truncated. Set
+  the ceiling to at least 1.5x the length wanted and trim with
+  `templates/audio-trim-fade`. This is also why a track whose
+  `duration_seconds` lands within 0.2 s of its ceiling should be read as cut
+  off rather than finished.
 - The engine caps a track at 9000 frames at 25 frames per second, 360 seconds.
   MiniMax supports five minutes; stay at or under 300.
 - The caption is capped at 5,000 tokens and a longer one is an error, not a
@@ -112,7 +134,13 @@ Control" section.
    second of audio and dominates, so time scales with the length the model
    actually sings, not the ceiling. Get the user's go-ahead before
    `run_workflow` with `acknowledged_cost=true`.
-3. `wait_for_job`, then `get_job` for the manifest.
+3. `wait_for_job`, then `get_job` for the manifest. Each manifest entry
+   carries `subfolder`: `templates/minimax/music-video` puts the cut in
+   `final` and the song, the singer's portrait and each shot in
+   `intermediate`, and `list_gallery(subfolder="final")` lists only
+   deliverables. Keep the convention in anything you compose from a template:
+   the step whose output the user will be shown is `final`, every other
+   saving step `intermediate`.
 4. You cannot listen: no tool returns audio inline. Hand the user the gallery
    `url` (`list_gallery`, or the manifest's file name) and check what you can
    yourself - `get_gallery_metadata` for the file's duration against the
diff --git a/tests/test_concat_videos.py b/tests/test_concat_videos.py
index 9fdb49f5..115e95e6 100644
--- a/tests/test_concat_videos.py
+++ b/tests/test_concat_videos.py
@@ -318,3 +318,83 @@ def test_a_path_joins_a_video_passed_in_directly(self, tmp_path):
 
         assert len(result.frames) == 8
         assert result.audio.shape[1] == 8 / 4 * 8000
+
+
+class TestLevelMatching:
+    """Independently generated shots land at whatever level the model chose,
+    and cutting a -2.6 dBFS shot against a -12.6 dBFS one is audible as a
+    drop no fade control can hide - see issue #82."""
+
+    def test_off_by_default(self):
+        loud, quiet = audio_video(4, 0.5), audio_video(4, 0.05)
+
+        result = concat_videos([loud, quiet])
+
+        assert result.audio[0][0] == pytest.approx(0.5)
+        assert result.audio[0][-1] == pytest.approx(0.05)
+
+    @pytest.mark.parametrize("measure", ["rms", "peak"])
+    def test_matching_brings_the_shots_to_one_level(self, measure):
+        loud, quiet = audio_video(4, 0.5), audio_video(4, 0.05)
+
+        result = concat_videos([loud, quiet], match_levels=measure)
+
+        # A steady tone's peak and rms are the same figure, so either
+        # measure lands both shots on the same sample value
+        head, tail = abs(result.audio[0][0]), abs(result.audio[0][-1])
+        assert head == pytest.approx(tail, rel=1e-3)
+
+    def test_the_target_level_is_the_callers_to_set(self):
+        result = concat_videos(
+            [audio_video(4, 0.5), audio_video(4, 0.05)],
+            match_levels="peak",
+            match_levels_dbfs=-6.0,
+        )
+
+        assert abs(result.audio[0][0]) == pytest.approx(10 ** (-6.0 / 20), rel=1e-3)
+
+    def test_a_gain_that_would_clip_is_held_below_full_scale(self, caplog):
+        # A track whose peak is far above its rms - matching the rms would
+        # ask for a gain that puts the peak past 0 dBFS
+        spiky = numpy.full((2, 100), 0.02, dtype=numpy.float32)
+        spiky[:, 50] = 0.9
+        video = AudioVideo(frames(4), spiky, 100)
+
+        result = concat_videos([video, audio_video(4, 0.02)], match_levels="rms")
+
+        assert float(numpy.abs(result.audio).max()) <= 1.0
+        assert "held to" in caplog.text
+
+    def test_a_silent_shot_is_left_alone(self):
+        silent = AudioVideo(frames(4), numpy.zeros((2, 100), dtype=numpy.float32), 100)
+
+        result = concat_videos([silent, audio_video(4, 0.5)], match_levels="rms")
+
+        assert float(numpy.abs(result.audio[:, :100]).max()) == 0.0
+
+    def test_a_shot_with_no_soundtrack_joins_as_before(self):
+        result = concat_videos([frames(4), audio_video(4, 0.5)], match_levels="rms")
+
+        assert result.audio is not None
+        assert len(result.frames) == 8
+
+    def test_an_unknown_measure_is_refused(self):
+        with pytest.raises(ValueError, match="match_levels"):
+            concat_videos([audio_video(4, 0.5)] * 2, match_levels="loudness")
+
+    def test_a_target_above_full_scale_is_refused(self):
+        with pytest.raises(ValueError, match="full scale"):
+            concat_videos(
+                [audio_video(4, 0.5)] * 2, match_levels="peak", match_levels_dbfs=3.0
+            )
+
+    def test_an_unmatched_join_warns_when_the_shots_are_levels_apart(self, caplog):
+        concat_videos([audio_video(4, 0.5), audio_video(4, 0.05)])
+
+        assert "level jump" in caplog.text
+        assert "match_levels" in caplog.text
+
+    def test_shots_already_at_one_level_draw_no_warning(self, caplog):
+        concat_videos([audio_video(4, 0.5), audio_video(4, 0.45)])
+
+        assert "level jump" not in caplog.text
diff --git a/tests/test_dissolve_videos.py b/tests/test_dissolve_videos.py
index c9844b19..d7935797 100644
--- a/tests/test_dissolve_videos.py
+++ b/tests/test_dissolve_videos.py
@@ -101,3 +101,29 @@ def test_mismatched_sample_rates_are_refused(self):
 
         with pytest.raises(ValueError, match="sample rate"):
             dissolve_videos([first, second], 2, fps=4)
+
+
+class TestLevelMatching:
+    """The same pair concat_videos carries (#82) - a dissolve joins
+    independently generated shots too, and a cross-dissolve between two
+    loudnesses is a swell, not a match."""
+
+    def test_matching_brings_the_shots_to_one_level(self):
+        result = dissolve_videos(
+            [audio_video(8, 0, 0.5), audio_video(8, 0, 0.05)],
+            dissolve_frames=0,
+            fps=4,
+            match_levels="peak",
+        )
+
+        assert abs(result.audio[0][0]) == pytest.approx(abs(result.audio[0][-1]))
+
+    def test_off_by_default_but_a_wide_spread_warns(self, caplog):
+        result = dissolve_videos(
+            [audio_video(8, 0, 0.5), audio_video(8, 0, 0.05)],
+            dissolve_frames=0,
+            fps=4,
+        )
+
+        assert abs(result.audio[0][-1]) == pytest.approx(0.05)
+        assert "level jump" in caplog.text
diff --git a/tests/test_host_memory.py b/tests/test_host_memory.py
new file mode 100644
index 00000000..2c1433da
--- /dev/null
+++ b/tests/test_host_memory.py
@@ -0,0 +1,97 @@
+"""Host memory readings beside the device ones (#81).
+
+`get_memory` is documented as VRAM *and* RAM, and on a box whose workflows
+offload weights to host memory by design, the host half is where a leak is
+visible at all.
+"""
+
+import builtins
+
+import pytest
+
+from dw import host_memory
+
+
+def test_stats_answer_this_process():
+    stats = host_memory.host_memory_stats()
+    assert set(stats) == {"rss_mb", "peak_rss_mb", "total_mb", "available_mb"}
+    # This test is itself a running python process, so its own footprint is
+    # measurable on every platform CI runs on
+    assert stats["rss_mb"] is None or stats["rss_mb"] > 1.0
+    if stats["total_mb"] is not None:
+        assert stats["total_mb"] > stats["available_mb"] - 1.0
+
+
+def test_fields_carry_the_payload_names():
+    fields = host_memory.host_memory_fields()
+    assert all(name.startswith("host_memory_") for name in fields)
+    # every name reported is one the payload declares
+    assert set(fields) <= set(host_memory.FIELD_NAMES.values())
+
+
+def test_a_reading_that_cannot_be_taken_is_absent_rather_than_null(monkeypatch):
+    monkeypatch.setattr(host_memory, "_psutil_stats", lambda: {"rss_mb": None})
+    monkeypatch.setattr(host_memory, "_proc_stats", lambda: {"rss_mb": None})
+    monkeypatch.setattr(host_memory, "_peak_rss_mb", lambda: None)
+    assert host_memory.host_memory_fields() == {}
+
+
+def test_a_failing_method_does_not_raise(monkeypatch):
+    def boom():
+        raise RuntimeError("no /proc here")
+
+    monkeypatch.setattr(host_memory, "_psutil_stats", boom)
+    monkeypatch.setattr(host_memory, "_proc_stats", boom)
+    stats = host_memory.host_memory_stats()
+    assert stats["rss_mb"] is None
+    assert stats["total_mb"] is None
+
+
+def test_the_stdlib_fallback_covers_a_machine_without_psutil(monkeypatch):
+    """psutil is opportunistic here, not a declared dependency."""
+    real_import = builtins.__import__
+
+    def no_psutil(name, *args, **kwargs):
+        if name == "psutil":
+            raise ImportError("no psutil")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", no_psutil)
+    stats = host_memory.host_memory_stats()
+    monkeypatch.undo()
+    # The peak comes from resource(2), which needs neither psutil nor /proc
+    assert stats["peak_rss_mb"] is None or stats["peak_rss_mb"] > 1.0
+
+
+def test_the_worker_reports_host_fields_beside_the_gpu_ones():
+    from dw.worker import WorkflowWorker
+
+    worker = WorkflowWorker.__new__(WorkflowWorker)
+    worker.run_count = 0
+    info = WorkflowWorker._get_memory_info(worker)
+
+    assert "gpu_memory_allocated_mb" in info
+    host = {k: v for k, v in info.items() if k.startswith("host_memory_")}
+    if host:  # a platform that can answer answers in MB, as the gpu keys do
+        assert all(isinstance(v, float) for v in host.values())
+        assert host["host_memory_rss_mb"] > 1.0
+
+
+@pytest.mark.parametrize("gpu_available", [True, False])
+def test_the_repl_prints_host_memory_either_way(capsys, gpu_available):
+    from dw.repl import DiffusersWorkflowREPL
+
+    repl = DiffusersWorkflowREPL.__new__(DiffusersWorkflowREPL)
+    DiffusersWorkflowREPL._print_memory_info(
+        repl,
+        {
+            "gpu_available": gpu_available,
+            "run_count": 1,
+            "host_memory_rss_mb": 1234.5,
+            "host_memory_total_mb": 64000.0,
+            "host_memory_available_mb": 32000.0,
+        },
+    )
+    out = capsys.readouterr().out
+    assert "Worker RSS: 1234.5 MB" in out
+    assert "32000.0 MB of 64000.0 MB" in out
diff --git a/tests/test_jobs_listing.py b/tests/test_jobs_listing.py
index 021885bd..61708df4 100644
--- a/tests/test_jobs_listing.py
+++ b/tests/test_jobs_listing.py
@@ -160,3 +160,42 @@ def test_mcp_list_jobs_passes_its_filters():
         "status": "failed,cancelled",
         "workspace": "qa",
     }
+
+
+def test_limit_larger_than_the_match_returns_every_match(server):
+    """A limit above the number of matching jobs is not a cut at all.
+
+    The slice used to be taken from `len(jobs) - limit`, which goes negative
+    once the limit exceeds what matched and then counts back from the end -
+    so a limit just above what matched answered with only the difference -
+    `limit=12` against 9 matching jobs returned 3 of them and called
+    the other 6 "not listed".
+    """
+    with server(success_script) as client:
+        ids = []
+        for _ in range(3):
+            job = client.post("/api/jobs", json={"workflow": valid_workflow()}).json()
+            wait_for_status(client, job["id"], {"succeeded"})
+            ids.append(job["id"])
+
+        body = client.get("/api/jobs", params={"limit": 4}).json()
+
+        assert body["total"] == 3
+        assert [job["id"] for job in body["jobs"]] == ids
+
+
+def test_limit_larger_than_the_match_under_a_status_filter(server):
+    """The shape the report came in: limit above the count, plus `status`."""
+    with server(success_script) as client:
+        ids = []
+        for _ in range(2):
+            job = client.post("/api/jobs", json={"workflow": valid_workflow()}).json()
+            wait_for_status(client, job["id"], {"succeeded"})
+            ids.append(job["id"])
+
+        body = client.get(
+            "/api/jobs", params={"limit": 3, "status": "succeeded"}
+        ).json()
+
+        assert body["total"] == 2
+        assert [entry["id"] for entry in body["jobs"]] == ids
diff --git a/tests/test_jobs_reused.py b/tests/test_jobs_reused.py
index fae0f6ce..bf8e5376 100644
--- a/tests/test_jobs_reused.py
+++ b/tests/test_jobs_reused.py
@@ -51,3 +51,19 @@ def test_job_for_file_still_finds_a_plain_writing_job(tmp_path):
     )
 
     assert history.job_for_file("test_image-0.0.png")["id"] == "writer"
+
+
+def test_job_for_file_attributes_a_file_in_a_subfolder(tmp_path):
+    # A step's result.subfolder puts a segment between the run id and the
+    # file; the recorded name and the gallery's name both carry it
+    history = JobHistory(str(tmp_path / "jobs.sqlite"))
+    name = "dialogue/20260912-120000-abcdef01/final/dialogue-assemble.0-0.0.png"
+
+    _record(
+        history,
+        "writer",
+        1.0,
+        [{"step": "assemble", "files": [name], "subfolder": "final"}],
+    )
+
+    assert history.job_for_file(name)["id"] == "writer"
diff --git a/tests/test_mcp_catalog.py b/tests/test_mcp_catalog.py
index 568f6899..4e36b9ff 100644
--- a/tests/test_mcp_catalog.py
+++ b/tests/test_mcp_catalog.py
@@ -102,6 +102,21 @@ def test_list_gallery_sends_its_limit():
     assert seen["params"]["limit"] == "7"
 
 
+def test_list_gallery_sends_a_subfolder_only_when_given():
+    client, seen = recording_client()
+    catalog.list_gallery(client, limit=7)
+    assert "subfolder" not in seen["params"]
+
+    client, seen = recording_client()
+    catalog.list_gallery(client, subfolder="final")
+    assert seen["params"]["subfolder"] == "final"
+
+    # '' is a real filter - files at a run's root - not "no filter"
+    client, seen = recording_client()
+    catalog.list_gallery(client, subfolder="")
+    assert seen["params"]["subfolder"] == ""
+
+
 def test_a_pass_through_tool_returns_the_body_unchanged():
     client, _seen = recording_client({"workflows": ["a"], "details": {}})
 
diff --git a/tests/test_pipeline_caching.py b/tests/test_pipeline_caching.py
index ae765dc8..f51413ca 100644
--- a/tests/test_pipeline_caching.py
+++ b/tests/test_pipeline_caching.py
@@ -267,8 +267,45 @@ def mock_pipeline_load(self, shared_components):
     kept_key = workflow._pipeline_keys_by_step["keep"]
     assert released_key not in pipeline_cache, "released pipeline should be evicted"
     assert kept_key in pipeline_cache, "other pipelines stay cached"
-    # the between-step cleanup returns cached blocks to the device
-    assert empty_cache.call_count == len(_release_workflow_def()["steps"])
+    # the between-step cleanup returns cached blocks to the device - once per
+    # step, plus once for the release itself, which reclaims where it drops
+    # rather than waiting for the end of the step
+    assert empty_cache.call_count == len(_release_workflow_def()["steps"]) + 1
+
+
+def test_release_pipeline_happens_before_the_result_is_written():
+    """A released pipeline is gone by the time the step writes its files.
+
+    The write does not touch the pipeline - the result is already in host
+    memory - and writing a long video is the longest phase of the step. A
+    release that waits for the write holds ~10 GB of weights on the device
+    for minutes after the last thing that needed them.
+    """
+    workflow = Workflow(_release_workflow_def(), "/tmp/test_output", "test.json")
+    pipeline_cache = {}
+    cached_at_save = {}
+
+    def mock_pipeline_load(self, shared_components):
+        self.pipeline = MagicMock()
+
+    def mock_run(self, *args, **kwargs):
+        result = MagicMock(result_list=[])
+        step_name = self.name
+
+        def save(*save_args, **save_kwargs):
+            key = workflow._pipeline_keys_by_step.get(step_name)
+            cached_at_save[step_name] = key in pipeline_cache
+            return []
+
+        result.save.side_effect = save
+        return result
+
+    with patch.object(Pipeline, "load", mock_pipeline_load):
+        with patch.object(Step, "run", mock_run):
+            with patch("dw.workflow.empty_device_cache"):
+                workflow.run({}, previous_pipelines=pipeline_cache)
+
+    assert cached_at_save == {"generate": False, "keep": True}
 
 
 def _release_models_workflow_def(release):
@@ -407,3 +444,44 @@ def mock_load(self, shared_components):
     assert (
         seen_at_load["old_still_cached"] is False
     ), "the redefined step's previous model must be evicted before load"
+
+
+def test_pipeline_released_is_reported_on_the_event_stream():
+    """The release is announced, and before the step's files are written.
+
+    A consumer cannot time the release by polling memory: it happens inside
+    the window between generation ending and the files appearing, which is
+    sub-second for an image step. The event is the ordered record that makes
+    it readable - see issue #75.
+    """
+    from dw.events import RunContext
+
+    events = []
+    workflow = Workflow(_release_workflow_def(), "/tmp/test_output", "test.json")
+
+    def mock_pipeline_load(self, shared_components):
+        self.pipeline = MagicMock()
+
+    with patch.object(Pipeline, "load", mock_pipeline_load):
+        with patch.object(
+            Step, "run", lambda self, *args, **kwargs: MagicMock(result_list=[])
+        ):
+            with patch("dw.workflow.empty_device_cache"):
+                workflow.run(
+                    {},
+                    previous_pipelines={},
+                    context=RunContext(on_event=events.append),
+                )
+
+    names = [e["event"] for e in events]
+    released = [e for e in events if e["event"] == "pipeline_released"]
+    assert len(released) == 1, "only the step that asked for it reports a release"
+    assert released[0]["step"] == "generate"
+    assert "gpu_memory_allocated_mb" in released[0]
+    assert "gpu_memory_allocated_before_mb" in released[0]
+
+    ends = [i for i, e in enumerate(events) if e["event"] == "step_end"]
+    assert names.index("pipeline_released") < ends[0], (
+        "the release is reported before the step reports its files - which is "
+        "the ordering the event exists to make visible"
+    )
diff --git a/tests/test_pipeline_components.py b/tests/test_pipeline_components.py
index 25e10f07..ba0a2ab1 100644
--- a/tests/test_pipeline_components.py
+++ b/tests/test_pipeline_components.py
@@ -602,3 +602,72 @@ def test_a_tensor_response_is_loaded(self, monkeypatch):
         embeds = remote.remote_text_encoder(["a mug"], "https://example.invalid", "cpu")
 
         assert embeds.shape == (2,)
+
+
+class TestFailedLoadIsTornDown:
+    """#72: a load that raises partway left what it had built resident.
+
+    Everything after the pipeline itself can fail - a quantized matmul pass, a
+    LoRA, a group-offload placement - and each failure used to hand the
+    workflow an exception with several GB still on the device, which the next
+    attempt then loaded on top of.
+    """
+
+    def _definition(self):
+        return {
+            "configuration": {"component_type": "{MockPipeline}"},
+            "from_pretrained_arguments": {"model_name": "some/repo"},
+            "arguments": {"prompt": "a cat"},
+        }
+
+    def _pipeline(self):
+        return Pipeline(self._definition(), 42, "cpu")
+
+    def test_a_load_that_fails_after_the_pipeline_is_built_drops_it(self, monkeypatch):
+        built = MagicMock()
+        monkeypatch.setattr(
+            "dw.pipeline_processors.pipeline.load_component",
+            lambda *args, **kwargs: built,
+        )
+        monkeypatch.setattr(
+            Pipeline,
+            "configure_loaded_components",
+            lambda self: (_ for _ in ()).throw(RuntimeError("placement failed")),
+        )
+        emptied = []
+        monkeypatch.setattr(
+            "dw.pipeline_processors.pipeline.empty_device_cache",
+            lambda *args, **kwargs: emptied.append(True),
+        )
+
+        pipeline = self._pipeline()
+        with pytest.raises(RuntimeError, match="placement failed"):
+            pipeline.load({})
+
+        assert pipeline.pipeline is None, "the half-loaded pipeline must be dropped"
+        assert emptied, "the device cache is emptied on the way out"
+
+    def test_a_failed_load_unpublishes_what_it_had_shared(self, monkeypatch):
+        """A component published before the failure would otherwise be handed
+        to a later step as if it belonged to a pipeline that exists."""
+        definition = self._definition()
+        definition["shared_components"] = ["vae"]
+        monkeypatch.setattr(
+            "dw.pipeline_processors.pipeline.load_component",
+            lambda *args, **kwargs: MagicMock(),
+        )
+        monkeypatch.setattr(
+            "dw.pipeline_processors.pipeline.load_loras",
+            lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("lora failed")),
+        )
+        monkeypatch.setattr(
+            "dw.pipeline_processors.pipeline.empty_device_cache",
+            lambda *args, **kwargs: None,
+        )
+
+        shared = {}
+        pipeline = Pipeline(definition, 42, "cpu")
+        with pytest.raises(RuntimeError, match="lora failed"):
+            pipeline.load(shared)
+
+        assert shared == {}
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index e1df1b7a..0f430944 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -9,6 +9,7 @@
 
 import glob
 import inspect
+import json
 import os
 import re
 
@@ -400,3 +401,41 @@ def test_the_music_video_ceiling_clears_its_slices(self):
         )
         spec = json.load(open(path, encoding="utf-8"))
         assert spec["variables"]["audio_duration"] >= 496 / 24 + 5
+
+
+@pytest.mark.parametrize(
+    "path", SKILLS, ids=lambda p: os.path.basename(os.path.dirname(p))
+)
+def test_a_skill_states_the_subfolder_convention(path):
+    """The templates put the deliverable in `final` and the scratch in
+    `intermediate`; an agent reading get_job needs to know that, and one
+    composing a new workflow needs to keep it."""
+    text = skill_text(path)
+    assert "`subfolder`" in text, f"{path} does not name the subfolder field"
+    assert (
+        "`final`" in text and "`intermediate`" in text
+    ), f"{path} does not state the final/intermediate convention"
+    # the convention is stated where the manifest is read
+    assert text.index("`subfolder`") > text.index("## Run and judge")
+
+
+def test_the_h3_skill_names_each_cut_templates_final_step():
+    """The skill names the one `final` step of each cut template - episode,
+    music_video, voyage; if a template's roles change the skill must change
+    with it."""
+    text = skill_text(H3_SKILL)
+    for name in ("dialogue-short", "music-video", "storyboard"):
+        path = os.path.join(
+            REPO_ROOT, "workflows", "templates", "minimax", name + ".json"
+        )
+        with open(path, encoding="utf-8") as f:
+            spec = json.load(f)
+        finals = [
+            step["name"]
+            for step in spec["steps"]
+            if (step.get("result") or {}).get("subfolder") == "final"
+        ]
+        assert len(finals) == 1, (name, finals)
+        assert (
+            f"`{finals[0]}`" in text
+        ), f"the skill does not name {name}'s final step {finals[0]}"
diff --git a/tests/test_runs.py b/tests/test_runs.py
index 6fe31398..fb4aece9 100644
--- a/tests/test_runs.py
+++ b/tests/test_runs.py
@@ -16,6 +16,8 @@
     manifest_relative_files,
     new_run_id,
     output_layout,
+    resolve_output_reference,
+    split_run_path,
     strip_run_id,
     workflow_identity,
 )
@@ -74,6 +76,40 @@ def test_a_path_with_no_run_id_keeps_its_folder(self):
         assert strip_run_id("ltx2/still.png") == "ltx2"
         assert strip_run_id("still.png") == ""
 
+    def test_splitting_a_run_path_names_its_three_parts(self):
+        run_id = new_run_id({"id": "x"})
+        assert split_run_path(f"ltx2/Gyre/{run_id}/still.png") == (
+            "ltx2/Gyre",
+            run_id,
+            "",
+        )
+        assert split_run_path(f"ltx2/Gyre/{run_id}/final/still.png") == (
+            "ltx2/Gyre",
+            run_id,
+            "final",
+        )
+        assert split_run_path(f"ltx2/Gyre/{run_id}/shots/act-1/x.mp4") == (
+            "ltx2/Gyre",
+            run_id,
+            "shots/act-1",
+        )
+        # A counter suffix is still a run id
+        assert split_run_path(f"Gyre/{run_id}-2/final/x.mp4") == (
+            "Gyre",
+            f"{run_id}-2",
+            "final",
+        )
+
+    def test_a_path_with_no_run_id_splits_to_its_directory(self):
+        # Flat layout: nothing to anchor on, so the directory is the identity
+        assert split_run_path("ltx2/final/still.png") == ("ltx2/final", "", "")
+        assert split_run_path("still.png") == ("", "", "")
+
+    def test_stripping_a_run_id_ignores_what_follows_it(self):
+        run_id = new_run_id({"id": "x"})
+        assert strip_run_id(f"ltx2/Gyre/{run_id}/final/still.png") == "ltx2/Gyre"
+        assert strip_run_id(f"{run_id}/final/still.png") == ""
+
     def test_a_run_id_with_tz_aware_utc_now_has_correct_stamp(self):
         # Verify that a tz-aware UTC now produces the correct timestamp prefix
         now = datetime(2026, 9, 5, 12, 34, 56, tzinfo=timezone.utc)
@@ -153,6 +189,12 @@ def _workflow_definition():
     }
 
 
+def _foldered_definition(subfolder="final"):
+    definition = _workflow_definition()
+    definition["steps"][0]["result"]["subfolder"] = subfolder
+    return definition
+
+
 @pytest.fixture
 def fake_pipeline():
     """A workflow run whose pipeline yields one small image."""
@@ -273,6 +315,23 @@ def test_the_manifest_records_the_seed_a_seedless_run_drew(
         # draws its own seed rather than inheriting this one
         assert "seed" not in definition
 
+    def test_a_drawn_seed_survives_a_trip_through_a_browser(
+        self, tmp_path, fake_pipeline
+    ):
+        """The seed reaches the web UI as JSON, where every integer is a
+        double: a 64-bit draw would be rounded on arrival, and the number
+        shown beside the image could not reproduce it."""
+        from dw.workflow import Workflow
+
+        definition = _workflow_definition()
+        del definition["seed"]
+        workflow = Workflow(definition, str(tmp_path), "/w/workflows/ltx2/Gyre.json")
+        workflow.run({"prompt": "a cat"})
+
+        run_dir = next((tmp_path / "ltx2" / "Gyre").iterdir())
+        manifest = json.loads((run_dir / "manifest.json").read_text())
+        assert 0 <= manifest["seed"] < 2**53
+
     def test_a_seed_can_come_from_a_variable(self, tmp_path, fake_pipeline):
         """'seed' accepts a 'variable:' reference, so a caller can re-run a
         workflow at the seed a previous run's manifest reported."""
@@ -412,3 +471,262 @@ def test_writing_it_returns_the_path(self, tmp_path):
         path = write_realized_workflow(str(tmp_path / "run"), {"id": "x"})
         assert path == str(tmp_path / "run" / "workflow.json")
         assert json.loads(open(path).read()) == {"id": "x"}
+
+
+class TestSubfolders:
+    def test_a_step_without_a_subfolder_writes_where_it_always_did(
+        self, tmp_path, fake_pipeline
+    ):
+        from dw.workflow import Workflow
+
+        Workflow(_workflow_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "runs_test-gen0.0-0.0.png").is_file()
+        assert not any(child.is_dir() for child in run.iterdir())
+
+    def test_a_step_with_a_subfolder_writes_into_it(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "final" / "runs_test-gen0.0-0.0.png").is_file()
+        assert not (run / "runs_test-gen0.0-0.0.png").exists()
+        # The manifest still sits at the root of the run
+        assert (run / "manifest.json").is_file()
+
+    def test_a_nested_subfolder_is_created(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(
+            _foldered_definition("shots/act-1"), str(tmp_path), "/w/workflows/Gyre.json"
+        ).run({})
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "shots" / "act-1" / "runs_test-gen0.0-0.0.png").is_file()
+
+    def test_step_output_dir_is_the_run_directory_without_a_subfolder(self, tmp_path):
+        from dw.workflow import Workflow
+
+        workflow = Workflow(
+            _workflow_definition(), str(tmp_path), "/w/workflows/Gyre.json"
+        )
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        step = workflow.workflow_definition["steps"][0]
+        assert workflow.step_output_dir(step) == workflow.effective_output_dir
+
+    def test_step_output_dir_refuses_an_escape_at_run_time(self, tmp_path):
+        from dw.security import SecurityError
+        from dw.workflow import Workflow
+
+        workflow = Workflow(
+            _foldered_definition("../other"), str(tmp_path), "/w/workflows/Gyre.json"
+        )
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        with pytest.raises(SecurityError):
+            workflow.step_output_dir(workflow.workflow_definition["steps"][0])
+
+    def test_the_pipeline_wrapper_is_pointed_at_the_subfolder(
+        self, tmp_path, fake_pipeline
+    ):
+        # A chain step's save_segments spill writes through the pipeline's
+        # output_dir, so it has to be the step's directory, not the run's
+        from dw.workflow import Workflow
+
+        workflow = Workflow(
+            _foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json"
+        )
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        step = workflow.workflow_definition["steps"][0]
+        action = workflow.create_step_action(step, {}, {}, 7, "cpu")
+        assert action.output_dir == os.path.join(workflow.effective_output_dir, "final")
+
+    def test_a_separator_in_file_base_name_is_refused_at_save(self, tmp_path):
+        from dw.result import Result
+        from dw.security import InvalidInputError
+
+        result = Result({"content_type": "image/png", "file_base_name": "final/"})
+        with pytest.raises(InvalidInputError, match="subfolder"):
+            result.save(str(tmp_path), "w-step.0")
+
+    def test_the_manifest_entry_carries_the_subfolder(self, tmp_path, fake_pipeline):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        manifest = json.loads((run / "manifest.json").read_text())
+        (entry,) = manifest["steps"]
+        assert entry["subfolder"] == "final"
+        assert entry["files"] == ["final/runs_test-gen0.0-0.0.png"]
+
+    def test_an_unfoldered_entry_carries_the_empty_string(
+        self, tmp_path, fake_pipeline
+    ):
+        from dw.workflow import Workflow
+
+        Workflow(_workflow_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        manifest = json.loads((run / "manifest.json").read_text())
+        assert manifest["steps"][0]["subfolder"] == ""
+
+    def test_a_reused_entry_carries_the_definitions_subfolder(
+        self, tmp_path, fake_pipeline
+    ):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        first, second = sorted((tmp_path / "Gyre").iterdir())
+        manifest = json.loads((second / "manifest.json").read_text())
+        (entry,) = manifest["steps"]
+        assert entry["reused"] is True
+        assert entry["subfolder"] == "final"
+        # The file is the first run's, absolute, inside its 'final'
+        assert os.path.dirname(entry["files"][0]) == str(first / "final")
+
+    def test_the_step_end_event_carries_the_subfolder(self, tmp_path, fake_pipeline):
+        from dw.events import RunContext
+        from dw.workflow import Workflow
+
+        seen = []
+        context = RunContext(on_event=seen.append)
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}, previous_pipelines={}, context=context
+        )
+        step_ends = [event for event in seen if event.get("event") == "step_end"]
+        assert step_ends and step_ends[0]["subfolder"] == "final"
+
+    def test_an_output_reference_reaches_into_a_subfolder(
+        self, tmp_path, fake_pipeline
+    ):
+        from dw.workflow import Workflow
+
+        Workflow(_foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json").run(
+            {}
+        )
+        (run,) = (tmp_path / "Gyre").iterdir()
+        resolved = resolve_output_reference(
+            "output:Gyre/latest/final/runs_test-gen0.0-0.0.png", root=str(tmp_path)
+        )
+        assert resolved == str(run / "final" / "runs_test-gen0.0-0.0.png")
+        assert (
+            resolve_output_reference(
+                f"output:Gyre/{run.name}/final/runs_test-gen0.0-0.0.png",
+                root=str(tmp_path),
+            )
+            == resolved
+        )
+
+    def test_a_for_each_member_lands_in_its_own_subfolder(
+        self, tmp_path, fake_pipeline
+    ):
+        # The design's showcase case: 'item:' routes each member, and an entry
+        # may spell its value through a variable
+        from dw.workflow import Workflow
+
+        definition = _workflow_definition()
+        definition["variables"] = {"scratch": "out"}
+        step = definition["steps"][0]
+        step["for_each"] = [
+            {"name": "a", "dest": "shots/a"},
+            {"name": "b", "dest": "variable:scratch"},
+        ]
+        step["result"]["subfolder"] = "item:dest"
+        Workflow(definition, str(tmp_path), "/w/workflows/Gyre.json").run({})
+        (run,) = (tmp_path / "Gyre").iterdir()
+        assert (run / "shots" / "a" / "runs_test-gen0@a.0-0.0.png").is_file()
+        assert (run / "out" / "runs_test-gen0@b.1-0.0.png").is_file()
+        manifest = json.loads((run / "manifest.json").read_text())
+        assert [e["subfolder"] for e in manifest["steps"]] == ["shots/a", "out"]
+
+    def test_a_symlinked_subfolder_cannot_escape_the_run(self, tmp_path):
+        # The shape check never sees this one - 'final' is a fine name - so
+        # it is containment, validate_output_path on the joined path, that
+        # has to refuse it
+        from dw.security import SecurityError
+        from dw.workflow import Workflow
+
+        workflow = Workflow(
+            _foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json"
+        )
+        run_dir = tmp_path / "Gyre" / "run"
+        run_dir.mkdir(parents=True)
+        elsewhere = tmp_path / "elsewhere"
+        elsewhere.mkdir()
+        (run_dir / "final").symlink_to(elsewhere)
+        workflow._run_dir = str(run_dir)
+        with pytest.raises(SecurityError):
+            workflow.step_output_dir(workflow.workflow_definition["steps"][0])
+
+    def test_the_first_run_id_shaped_segment_wins(self):
+        first = new_run_id({"id": "x"})
+        second = new_run_id({"id": "y"})
+        assert split_run_path(f"Gyre/{first}/{second}/x.png") == ("Gyre", first, second)
+
+    def test_a_parents_subfolder_does_not_move_a_childs_files(
+        self, tmp_path, fake_pipeline
+    ):
+        # A 'workflow' step's own result block governs what the parent saves
+        # from the child's return value; the child's steps place their own
+        # files, into the run directory they inherit
+        from dw.workflow import Workflow
+
+        tree = tmp_path / "workflows"
+        tree.mkdir()
+        (tree / "child.json").write_text(json.dumps(_workflow_definition()))
+        parent = {
+            "id": "parent",
+            "seed": 7,
+            "steps": [
+                {
+                    "name": "child",
+                    "workflow": {"path": "child.json"},
+                    "result": {"subfolder": "final"},
+                }
+            ],
+        }
+        Workflow(parent, str(tmp_path / "out"), str(tree / "Parent.json")).run({})
+        (run,) = (tmp_path / "out" / "Parent").iterdir()
+        assert (run / "runs_test-gen0.0-0.0.png").is_file()
+        assert not (run / "final" / "runs_test-gen0.0-0.0.png").exists()
+
+    def test_a_chain_spill_lands_in_the_steps_subfolder(self, tmp_path, fake_pipeline):
+        # save_segments writes through the pipeline wrapper's output_dir,
+        # which create_step_action points at the step's subfolder
+        from dw.pipeline_processors.chain import run_chain
+        from dw.workflow import Workflow
+        from tests.test_chain import FakePipeline, video_output
+
+        workflow = Workflow(
+            _foldered_definition(), str(tmp_path), "/w/workflows/Gyre.json"
+        )
+        workflow._run_dir = str(tmp_path / "Gyre" / "run")
+        action = workflow.create_step_action(
+            workflow.workflow_definition["steps"][0], {}, {}, 7, "cpu"
+        )
+        spilling = FakePipeline(
+            video_output, output_dir=action.output_dir, file_prefix=action.file_prefix
+        )
+        run_chain(
+            spilling,
+            {
+                "segments": 2,
+                "trim_frames": 1,
+                "fps": 4,
+                "save_segments": True,
+                "keep_segments": True,
+            },
+            {},
+        )
+        segments = sorted((tmp_path / "Gyre" / "run" / "final").glob("*.segment-*.mp4"))
+        assert len(segments) == 2
diff --git a/tests/test_schema.py b/tests/test_schema.py
index f4bff1f1..1303a56d 100644
--- a/tests/test_schema.py
+++ b/tests/test_schema.py
@@ -431,3 +431,29 @@ def test_an_empty_for_each_list_fails_schema_validation():
     errors = validate_data_all(base, schema)
     assert errors != []
     assert any("for_each" in e["path"] for e in errors)
+
+
+class TestResultSubfolder:
+    def test_subfolder_is_a_described_string_with_no_pattern(self):
+        result = load_schema("workflow")["$defs"]["result"]["properties"]
+        assert result["subfolder"]["type"] == "string"
+        assert "final" in result["subfolder"]["description"]
+        # Schema validation runs before substitution, so a pattern would
+        # reject 'variable:dest' and 'item:subfolder'
+        assert "pattern" not in result["subfolder"]
+
+    def test_a_workflow_with_a_subfolder_validates(self):
+        definition = {
+            "id": "s",
+            "steps": [
+                {
+                    "name": "a",
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {
+                        "content_type": "image/png",
+                        "subfolder": "variable:dest",
+                    },
+                }
+            ],
+        }
+        assert validate_data_all(definition, load_schema("workflow")) == []
diff --git a/tests/test_security.py b/tests/test_security.py
index 5acedc63..ef1c923d 100644
--- a/tests/test_security.py
+++ b/tests/test_security.py
@@ -473,5 +473,56 @@ def test_every_security_error_shares_one_base_class(self):
         assert issubclass(InvalidInputError, SecurityError)
 
 
+class TestSubfolderValidation:
+    def test_a_segment_path_is_accepted(self):
+        from dw.security import validate_subfolder
+
+        assert validate_subfolder("final") == "final"
+        assert validate_subfolder("shots/act-1") == "shots/act-1"
+        assert validate_subfolder("a.b_c-d/e") == "a.b_c-d/e"
+
+    @pytest.mark.parametrize(
+        "bad",
+        [
+            "",
+            "../final",
+            "final/..",
+            "/final",
+            "final/",
+            "final//x",
+            ".hidden",
+            "-dash",
+            "final\\x",
+            "final x",
+            "fin:al",
+        ],
+    )
+    def test_the_shape_refuses_what_output_references_refuse(self, bad):
+        from dw.security import InvalidInputError, validate_subfolder
+
+        with pytest.raises(InvalidInputError):
+            validate_subfolder(bad)
+
+    def test_too_long_is_refused(self):
+        from dw.security import InvalidInputError, validate_subfolder
+
+        with pytest.raises(InvalidInputError):
+            validate_subfolder("a" * 201)
+
+
+class TestFileBaseNameValidation:
+    def test_a_plain_name_is_accepted(self):
+        from dw.security import validate_file_base_name
+
+        assert validate_file_base_name("episode_") == "episode_"
+
+    @pytest.mark.parametrize("bad", ["final/", "a/b", "a\\b"])
+    def test_a_separator_is_refused_and_names_subfolder(self, bad):
+        from dw.security import InvalidInputError, validate_file_base_name
+
+        with pytest.raises(InvalidInputError, match="subfolder"):
+            validate_file_base_name(bad)
+
+
 if __name__ == "__main__":
     pytest.main([__file__])
diff --git a/tests/test_server.py b/tests/test_server.py
index 0deee1b7..7c4f0679 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -689,10 +689,13 @@ def test_a_silently_killed_worker_reports_its_exit_and_frees_the_manager(tmp_pat
         # used to answer 503
         response = client.get("/api/memory")
         assert response.status_code == 200
-        assert response.json() == {
-            "live": False,
-            "info": {"gpu_available": True, "used": 42},
-        }
+        body = response.json()
+        assert body["live"] is False
+        assert body["info"] == {"gpu_available": True, "used": 42}
+        # and it says the figure is not this moment's, so a caller does not
+        # compare it against a live one
+        assert body["stale"] is True
+        assert body["reason"] == "worker_stopped"
 
 
 def test_a_slow_worker_is_not_declared_dead(tmp_path):
@@ -714,14 +717,48 @@ def crash_details(self):
     manager.worker_manager.worker_active = True
     manager.last_memory = {"gpu_available": True}
 
-    assert manager.memory_status(timeout=0.01) == {
-        "live": False,
-        "info": {"gpu_available": True},
-    }
+    status = manager.memory_status(timeout=0.01)
+    assert status["live"] is False
+    assert status["info"] == {"gpu_available": True}
+    assert status["stale"] is True
+    assert status["reason"] == "worker_unreachable"
     assert manager.worker_manager.worker_active is True
     assert getattr(manager.worker_manager, "crashed", False) is False
 
 
+def test_memory_says_why_a_reading_is_not_the_worker_s(tmp_path):
+    """The three states a caller has to tell apart: no reading at all, a
+    cached one taken while the worker is busy, and a live one. Only the last
+    is the worker's memory now, and only those are comparable with each
+    other - a reading cached mid-load understates what is resident."""
+    manager = JobManager(
+        str(tmp_path / "outputs"),
+        worker_manager=ScriptedWorkerManager(success_script),
+        history_path=str(tmp_path / "jobs.sqlite"),
+    )
+
+    # (a) nothing has ever been measured, which means nothing is resident
+    stopped = manager.memory_status()
+    assert stopped == {
+        "live": False,
+        "info": None,
+        "stale": False,
+        "reason": "worker_stopped",
+        "age_seconds": None,
+    }
+
+    # (b) a job is running, so the reading on file predates it
+    manager._record_memory({"gpu_memory_allocated_mb": 8.125})
+    manager.last_memory_at -= 60
+    manager._current_job_id = "abc"
+    busy = manager.memory_status()
+    assert busy["live"] is False
+    assert busy["stale"] is True
+    assert busy["reason"] == "job_running"
+    assert busy["age_seconds"] >= 60
+    assert busy["info"] == {"gpu_memory_allocated_mb": 8.125}
+
+
 def test_health_and_memory(server):
     import socket
 
@@ -738,6 +775,9 @@ def test_health_and_memory(server):
         memory = client.get("/api/memory").json()
         assert memory["live"] is True
         assert memory["info"]["gpu_available"] is True
+        # a live reading is nobody's cache
+        assert memory["stale"] is False
+        assert memory["reason"] is None
 
 
 def test_introspection_endpoints(server):
@@ -1299,6 +1339,63 @@ def test_gallery_paginates_and_groups_by_workflow_folder(server, tmp_path):
         assert not (outputs / "ltx" / "nested-0.png").exists()
 
 
+def test_gallery_reports_and_filters_by_subfolder(server, tmp_path):
+    """A step's `result.subfolder` puts its files under
+    '<identity>/<run id>/<subfolder>/'. The gallery keeps `folder` meaning
+    the workflow identity - a workflow run fifty times is still one folder
+    - and carries the in-run subfolder as its own axis, so 'which workflow'
+    and 'which part of the run' never multiply into one filter list."""
+    from PIL import Image
+
+    from dw.runs import new_run_id
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        run_id = new_run_id({"id": "dialogue"})
+        run = outputs / "dialogue" / run_id
+        (run / "final").mkdir(parents=True)
+        (run / "intermediate" / "shots").mkdir(parents=True)
+        Image.new("RGB", (2, 2)).save(run / "final" / "dialogue-assemble.0-0.0.png")
+        Image.new("RGB", (2, 2)).save(run / "intermediate" / "dialogue-shot.0-0.0.png")
+        Image.new("RGB", (2, 2)).save(
+            run / "intermediate" / "shots" / "dialogue-slice.0-0.0.png"
+        )
+        Image.new("RGB", (2, 2)).save(run / "dialogue-still.0-0.0.png")
+        # a flat-layout file: no run id, so nothing to hang a subfolder on
+        (outputs / "ltx").mkdir()
+        Image.new("RGB", (2, 2)).save(outputs / "ltx" / "flat.png")
+
+        full = client.get("/api/gallery").json()
+        by_name = {f["name"]: f for f in full["files"]}
+
+        # folder is the identity, subfolder is what followed the run id
+        final = by_name[f"dialogue/{run_id}/final/dialogue-assemble.0-0.0.png"]
+        assert final["folder"] == "dialogue"
+        assert final["subfolder"] == "final"
+        nested = by_name[
+            f"dialogue/{run_id}/intermediate/shots/dialogue-slice.0-0.0.png"
+        ]
+        assert nested["subfolder"] == "intermediate/shots"
+        assert by_name[f"dialogue/{run_id}/dialogue-still.0-0.0.png"]["subfolder"] == ""
+        assert by_name["ltx/flat.png"]["folder"] == "ltx"
+        assert by_name["ltx/flat.png"]["subfolder"] == ""
+
+        # the two axes stay separate
+        assert set(full["folders"]) == {"", "dialogue", "ltx"}
+        assert full["subfolders"] == ["", "final", "intermediate", "intermediate/shots"]
+
+        # the filter narrows listing and total; combined with folder it intersects
+        finals = client.get("/api/gallery?subfolder=final").json()
+        assert finals["total"] == 1
+        assert finals["files"][0]["subfolder"] == "final"
+        both = client.get("/api/gallery?folder=dialogue&subfolder=").json()
+        assert {f["name"] for f in both["files"]} == {
+            f"dialogue/{run_id}/dialogue-still.0-0.0.png"
+        }
+        # subfolders is over the whole tree, not the filtered page
+        assert finals["subfolders"] == full["subfolders"]
+
+
 def test_gallery_thumbnail_is_smaller_than_the_original(server, tmp_path):
     from PIL import Image
 
diff --git a/tests/test_subfolders.py b/tests/test_subfolders.py
new file mode 100644
index 00000000..75098f04
--- /dev/null
+++ b/tests/test_subfolders.py
@@ -0,0 +1,141 @@
+import pytest
+
+from dw.security import InvalidInputError
+from dw.subfolders import step_subfolder, subfolder_errors
+
+
+def _step(name, result=None, **extra):
+    step = {"name": name, "task": {"command": "noop", "arguments": {}}}
+    if result is not None:
+        step["result"] = result
+    step.update(extra)
+    return step
+
+
+class TestStepSubfolder:
+    def test_absent_is_the_empty_string(self):
+        assert step_subfolder(_step("a")) == ""
+        assert step_subfolder(_step("a", {"content_type": "image/png"})) == ""
+
+    def test_present_is_returned_validated(self):
+        assert step_subfolder(_step("a", {"subfolder": "final"})) == "final"
+
+    def test_a_bad_one_raises(self):
+        with pytest.raises(InvalidInputError):
+            step_subfolder(_step("a", {"subfolder": "../x"}))
+
+    def test_a_non_string_raises(self):
+        with pytest.raises(InvalidInputError):
+            step_subfolder(_step("a", {"subfolder": 3}))
+
+
+class TestSubfolderErrors:
+    def test_a_clean_definition_has_none(self):
+        definition = {
+            "steps": [
+                _step("a", {"content_type": "image/png", "subfolder": "final"}),
+                _step("b", {"content_type": "image/png"}),
+            ]
+        }
+        assert subfolder_errors(definition) == []
+
+    def test_a_bad_subfolder_is_reported_at_its_path(self):
+        definition = {"steps": [_step("a", {"subfolder": "../escape"})]}
+        errors = subfolder_errors(definition)
+        assert len(errors) == 1
+        assert errors[0]["path"] == "steps[0].result.subfolder"
+        assert (
+            "Subfolder" in errors[0]["message"] or "subfolder" in errors[0]["message"]
+        )
+
+    def test_a_separator_in_file_base_name_is_reported_at_its_path(self):
+        definition = {"steps": [_step("a", {"file_base_name": "final/"})]}
+        errors = subfolder_errors(definition)
+        assert [e["path"] for e in errors] == ["steps[0].result.file_base_name"]
+        assert "subfolder" in errors[0]["message"]
+
+    def test_an_expanded_member_reports_the_source_step_and_names_the_member(self):
+        # expand_for_each turned steps[1] into two members; the author wrote
+        # one step, so the path is the source's and the member is named
+        definition = {
+            "steps": [
+                _step("intro", {"subfolder": "final"}),
+                _step("shot@a", {"subfolder": "ok"}),
+                _step("shot@b", {"subfolder": "bad/../x"}),
+            ]
+        }
+        errors = subfolder_errors(definition, source_indices=[0, 1, 1])
+        assert len(errors) == 1
+        assert errors[0]["path"] == "steps[1].result.subfolder"
+        assert "shot@b" in errors[0]["message"]
+
+    def test_an_unsubstituted_reference_is_left_alone(self):
+        # A 'variable:' still spelled out is one nothing resolved; that is
+        # the undeclared-variable pass's complaint, not this one's
+        definition = {"steps": [_step("a", {"subfolder": "variable:dest"})]}
+        assert subfolder_errors(definition) == []
+
+    def test_no_steps_is_fine(self):
+        assert subfolder_errors({}) == []
+        assert subfolder_errors({"steps": "nope"}) == []
+
+
+class TestValidationErrorsIntegration:
+    def _workflow(self, definition, tmp_path):
+        from dw.workflow import Workflow
+
+        return Workflow(definition, str(tmp_path), "/w/workflows/Sub.json")
+
+    def test_validation_errors_reports_a_bad_subfolder(self, tmp_path):
+        definition = {
+            "id": "sub_test",
+            "steps": [
+                {
+                    "name": "a",
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {"content_type": "image/png", "subfolder": "../x"},
+                }
+            ],
+        }
+        errors = self._workflow(definition, tmp_path).validation_errors()
+        assert [e["path"] for e in errors] == ["steps[0].result.subfolder"]
+
+    def test_a_variable_driven_subfolder_is_checked_by_its_value(self, tmp_path):
+        definition = {
+            "id": "sub_test",
+            "variables": {"dest": "final"},
+            "steps": [
+                {
+                    "name": "a",
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {
+                        "content_type": "image/png",
+                        "subfolder": "variable:dest",
+                    },
+                }
+            ],
+        }
+        workflow = self._workflow(definition, tmp_path)
+        assert workflow.validation_errors() == []
+        errors = workflow.validation_errors(arguments={"dest": "../x"})
+        assert [e["path"] for e in errors] == ["steps[0].result.subfolder"]
+
+    def test_an_item_driven_subfolder_is_checked_per_member(self, tmp_path):
+        definition = {
+            "id": "sub_test",
+            "steps": [
+                {
+                    "name": "shot",
+                    "for_each": [
+                        {"name": "a", "dest": "shots/a"},
+                        {"name": "b", "dest": "../x"},
+                    ],
+                    "task": {"command": "noop", "arguments": {}},
+                    "result": {"content_type": "image/png", "subfolder": "item:dest"},
+                }
+            ],
+        }
+        errors = self._workflow(definition, tmp_path).validation_errors()
+        assert len(errors) == 1
+        assert errors[0]["path"] == "steps[0].result.subfolder"
+        assert "shot@b" in errors[0]["message"]
diff --git a/tests/test_template_subfolders.py b/tests/test_template_subfolders.py
new file mode 100644
index 00000000..860a696f
--- /dev/null
+++ b/tests/test_template_subfolders.py
@@ -0,0 +1,92 @@
+"""Every multi-step template says which of its outputs is the deliverable.
+
+A run writes everything into one directory, so a finished episode sits
+beside the scratch that went into it. A step's `result.subfolder` places
+its files - by convention `final` for the deliverable and `intermediate`
+for the rest (docs/WORKFLOW_GUIDE.md, "Saying which output is the
+deliverable"). Agents compose by copying a template, so the convention
+propagates only if every shipped template follows it; this test is what
+keeps it from drifting.
+
+The rule, from docs/proposals/output-folders.md: a *saving step* is one
+whose `result` sets `content_type` and does not set `save: false`; a
+template is in scope when it has two or more saving steps; every saving
+step of an in-scope template carries `final` or `intermediate`, and at
+least one is `final`. The packaged builtins in dw/workflows/ stay unmarked:
+a builtin is a step list a parent composes, and a role is the parent's to
+assign - the parent's own `result` block, not the child's, is where it
+says so.
+"""
+
+import json
+import os
+
+import pytest
+
+from tests.test_examples import BUILTIN_DIR, REPO_ROOT, get_example_files
+
+CONVENTION = {"final", "intermediate"}
+
+
+def load(relative_path):
+    with open(os.path.join(REPO_ROOT, relative_path), encoding="utf-8") as file:
+        return json.load(file)
+
+
+def saving_steps(definition):
+    """The steps whose result is written to disk."""
+    for step in definition.get("steps", []):
+        result = step.get("result") or {}
+        if result.get("content_type") and result.get("save", True) is not False:
+            yield step
+
+
+TEMPLATES = [f for f in get_example_files() if f.startswith("workflows/templates/")]
+IN_SCOPE = [f for f in TEMPLATES if len(list(saving_steps(load(f)))) >= 2]
+
+
+def test_the_scope_is_what_the_design_counted():
+    """Eighteen templates had two or more saving steps when the convention
+    landed. A template added later with several saving steps joins the
+    parametrized test below on its own; this pins that none has quietly
+    left it (a step that stopped saving would drop a template from scope
+    without failing anything else)."""
+    assert len(IN_SCOPE) >= 18, IN_SCOPE
+
+
+@pytest.mark.parametrize("template", IN_SCOPE)
+def test_every_saving_step_of_a_multi_step_template_names_its_role(template):
+    steps = list(saving_steps(load(template)))
+    roles = {step["name"]: step["result"].get("subfolder") for step in steps}
+
+    unmarked = sorted(name for name, role in roles.items() if role not in CONVENTION)
+    assert (
+        not unmarked
+    ), f"{template}: saving steps without a final/intermediate subfolder: {unmarked}"
+    assert "final" in roles.values(), f"{template}: no step is marked final"
+
+
+@pytest.mark.parametrize("template", IN_SCOPE)
+def test_the_subfolder_is_the_last_key_of_the_result(template):
+    """One added line per step, and every template reads alike."""
+    for step in saving_steps(load(template)):
+        assert (
+            list(step["result"])[-1] == "subfolder"
+        ), f"{template}: step {step['name']!r} does not end its result with subfolder"
+
+
+@pytest.mark.parametrize(
+    "builtin",
+    sorted(name for name in os.listdir(BUILTIN_DIR) if name.endswith(".json")),
+)
+def test_the_packaged_builtins_stay_unmarked(builtin):
+    with open(os.path.join(BUILTIN_DIR, builtin), encoding="utf-8") as file:
+        definition = json.load(file)
+    marked = [
+        step["name"]
+        for step in definition.get("steps", [])
+        if "subfolder" in (step.get("result") or {})
+    ]
+    assert (
+        not marked
+    ), f"dw/workflows/{builtin} marks {marked}; a role is the parent's to assign"
diff --git a/tests/test_worker_execute.py b/tests/test_worker_execute.py
index f73ee9e7..1ff46154 100644
--- a/tests/test_worker_execute.py
+++ b/tests/test_worker_execute.py
@@ -195,3 +195,72 @@ def test_a_failure_before_the_workflow_loads_reports_no_manifest():
         )
     error = next(m for m in _drain(worker.result_queue) if m["type"] == "error")
     assert error["manifest"] == []
+
+
+def test_a_failed_run_reclaims_memory_and_drops_untouched_pipelines():
+    """#72: a run that fails leaks everything it had loaded.
+
+    Success and cancellation both reclaim; failure did neither, so a
+    half-loaded pipeline and any variant the failed attempt superseded stayed
+    resident - and the next attempt loaded its own on top of them, which is
+    how three retries starved a decode by 1.88 GiB.
+    """
+
+    class FailingWorkflow(StubWorkflow):
+        def run(self, arguments, previous_pipelines=None, context=None):
+            context.touch_pipeline("kept-key")
+            raise RuntimeError("CUDA out of memory")
+
+    worker = _make_worker()
+    worker.loaded_pipelines["kept-key"] = object()
+    worker.loaded_pipelines["dead-variant"] = object()
+
+    with patch.object(worker, "_cleanup_between_runs") as cleanup:
+        messages = _execute(worker, FailingWorkflow())
+
+    assert "error" in [message["type"] for message in messages]
+    cleanup.assert_called_once()
+    # the variant this run never touched is dead weight - the one it did touch
+    # is still the warm model a retry would reuse
+    assert "dead-variant" not in worker.loaded_pipelines
+    assert "kept-key" in worker.loaded_pipelines
+
+
+def test_a_failed_run_drops_the_traceback_before_reclaiming():
+    """The traceback is what pins a half-finished load in memory.
+
+    Every frame between the handler and the failure is reachable through
+    `__traceback__`, and those frames hold whatever the load had built when it
+    raised - so a collection that runs while the exception is still live frees
+    none of it. The report is a formatted string by then, so the traceback
+    goes first and the reclaim afterwards has something to reclaim.
+    """
+    import gc
+    import weakref
+
+    class Weight:
+        pass
+
+    held = []
+    alive_at_cleanup = []
+
+    class FailingWorkflow(StubWorkflow):
+        def run(self, arguments, previous_pipelines=None, context=None):
+            half_loaded = Weight()
+            held.append(weakref.ref(half_loaded))
+            raise RuntimeError("load failed partway")
+
+    worker = _make_worker()
+
+    def record():
+        gc.collect()
+        alive_at_cleanup.append(held[0]() is not None)
+
+    # the log record itself carries exc_info, and pytest's capture keeps every
+    # record for the length of the test - which would pin the traceback here
+    # no matter what the worker does with it
+    with patch("dw.worker.logger"):
+        with patch.object(worker, "_cleanup_between_runs", side_effect=record):
+            _execute(worker, FailingWorkflow())
+
+    assert alive_at_cleanup == [False]
diff --git a/tests/test_workflow_step_cache.py b/tests/test_workflow_step_cache.py
index 9bfa7790..7818672f 100644
--- a/tests/test_workflow_step_cache.py
+++ b/tests/test_workflow_step_cache.py
@@ -418,6 +418,7 @@ def test_cache_hit_marks_its_manifest_entry_and_event_reused():
             {
                 "step": "generate",
                 "files": workflow.manifest[0]["files"],
+                "subfolder": "",
                 "reused": True,
             }
         ]
diff --git a/ui/src/lib/api.ts b/ui/src/lib/api.ts
index 00b8c9bd..34c7bf15 100644
--- a/ui/src/lib/api.ts
+++ b/ui/src/lib/api.ts
@@ -58,6 +58,24 @@ function withToken(url: string): string {
   return token ? appendQuery(scopedUrl, 'token', token) : scopedUrl
 }
 
+/** Scope a path to an explicit workspace instead of the picker's current
+ * selection - for a job's own files, which must resolve to where they were
+ * written even if the picker has since moved elsewhere. Mirrors `scoped()`. */
+function workspaceScopedPath(
+  path: string,
+  workspace: string | undefined,
+): string {
+  if (workspace === undefined || workspace === DEFAULT_WORKSPACE) return path
+  return appendQuery(path, 'workspace', workspace)
+}
+
+/** `withToken`, scoped to an explicit workspace rather than the picker's. */
+function withTokenIn(url: string, workspace: string): string {
+  const scopedUrl = workspaceScopedPath(url, workspace)
+  const token = getApiToken()
+  return token ? appendQuery(scopedUrl, 'token', token) : scopedUrl
+}
+
 /** The URL an output file is served from. Jobs report files by their name
  * relative to the output directory - a workflow under a subfolder writes
  * to '<sub>/<file>' - so the whole relative path is kept. A job recorded
@@ -389,12 +407,22 @@ export const api = {
   // Loads the whole gallery in one request, like listWorkflows/listPrompts -
   // the limit just needs to exceed any real output directory's file count
   gallery: () => request<{ files: GalleryFile[] }>('/api/gallery?limit=100000'),
-  galleryMetadata: (name: string) =>
+  // `workspace`, when given, names the file's own workspace and wins over
+  // whatever is currently selected in the picker - mirrors `outputUrl`, since
+  // a job page must read its own files from where they were written
+  galleryMetadata: (name: string, workspace?: string) =>
     request<{
       name: string
       metadata: Record<string, unknown> | null
       job: { id: string; status: string } | null
-    }>(`/api/gallery/${encodePath(name)}/metadata`),
+    }>(
+      workspaceScopedPath(
+        `/api/gallery/${encodePath(name)}/metadata`,
+        workspace,
+      ),
+      undefined,
+      { scope: workspace === undefined },
+    ),
   galleryThumbnailUrl: (name: string) =>
     withToken(`/api/gallery/${encodePath(name)}/thumbnail`),
   deleteOutput: (name: string) =>
@@ -402,8 +430,10 @@ export const api = {
       `/api/gallery/${encodePath(name)}`,
       { method: 'DELETE' },
     ),
-  outputDownloadUrl: (name: string) =>
-    withToken(`/api/gallery/${encodePath(name)}/download`),
+  outputDownloadUrl: (name: string, workspace?: string) =>
+    workspace === undefined
+      ? withToken(`/api/gallery/${encodePath(name)}/download`)
+      : withTokenIn(`/api/gallery/${encodePath(name)}/download`, workspace),
   /** Download a multi-file gallery selection as one zip. The browser
    * cannot zip on its own and throttles a burst of single downloads, so
    * the server bundles the selection and this saves the response. */
diff --git a/ui/src/lib/pages/GalleryPage.svelte b/ui/src/lib/pages/GalleryPage.svelte
index 23ce63a5..11b35491 100644
--- a/ui/src/lib/pages/GalleryPage.svelte
+++ b/ui/src/lib/pages/GalleryPage.svelte
@@ -22,6 +22,10 @@
   let files = $state<GalleryFile[]>([])
   let loaded = $state(false)
   let filter = $state('')
+  // The in-run subfolder to show - null is every one. Only offered when
+  // some output landed in one; a workspace of unfoldered runs never sees
+  // the control
+  let subfolder = $state<string | null>(null)
   let error = $state('')
   let selected = $state<GalleryFile | null>(null)
   // Names ticked in the grid, for the bulk actions
@@ -84,9 +88,37 @@
     }
   }
 
+  // Every distinct subfolder in the listing - read off the entries so a
+  // delete updates it without a refetch. '' (the run root) appears only
+  // when some file sits there, so the pick never offers an empty option
+  const subfolders = $derived(
+    [...new Set(files.map((f) => f.subfolder))].sort((a, b) =>
+      a.localeCompare(b),
+    ),
+  )
+  const subfolderOffered = $derived(subfolders.some((s) => s !== ''))
+  const filterActive = $derived(filter !== '' || subfolder !== null)
   const visible = $derived(
-    files.filter((f) => f.name.toLowerCase().includes(filter.toLowerCase())),
+    files.filter(
+      (f) =>
+        f.name.toLowerCase().includes(filter.toLowerCase()) &&
+        (subfolder === null || f.subfolder === subfolder),
+    ),
   )
+  // A pick that no longer exists (its last file deleted) means everything,
+  // not an empty grid pinned to a vanished value - and the control itself
+  // is reset, since a <select> whose value matches no option shows blank.
+  // A pick of '' (the run root) never appears in `subfolders` on its own,
+  // so it is only cleared once the control itself stops being offered -
+  // otherwise it would survive the control unmounting and leave
+  // `filterActive` stuck true with nothing to reset it
+  $effect(() => {
+    if (
+      subfolder !== null &&
+      (!subfolderOffered || !subfolders.includes(subfolder))
+    )
+      subfolder = null
+  })
   const byName = $derived(new Map(visible.map((f) => [f.name, f])))
   // The server folds each run id into `folder`; group by that, since the
   // name alone reads the run directory as one more folder
@@ -278,6 +310,19 @@
   <WorkspacePicker />
   <span class="num muted">{files.length} files</span>
   <input class="filter" placeholder="filter…" bind:value={filter} />
+  {#if subfolderOffered}
+    <select
+      class="subfolderpick"
+      aria-label="subfolder"
+      title="show only files a step saved to this subfolder of its run"
+      bind:value={subfolder}
+    >
+      <option value={null}>all subfolders</option>
+      {#each subfolders as s (s)}
+        <option value={s}>{s === '' ? '(run root)' : `${s}/`}</option>
+      {/each}
+    </select>
+  {/if}
 </div>
 
 {#if error}<p class="muted">Could not read the gallery: {error}</p>{/if}
@@ -307,7 +352,7 @@
     class="quiet"
     onclick={selectAllVisible}
     disabled={visible.length === 0}
-    >Select all{filter ? ' matching' : ''} ({visible.length})</button
+    >Select all{filterActive ? ' matching' : ''} ({visible.length})</button
   >
 </div>
 
@@ -315,7 +360,7 @@
   names={visible.map((f) => f.name)}
   groupOf={(name) => folderByName.get(name) ?? ''}
   collapseKey="collapsed-gallery-folders"
-  filterActive={filter !== ''}
+  {filterActive}
   minColumn="150px"
 >
   {#snippet card(name)}
@@ -419,7 +464,7 @@
             </div>{/if}
           {#if metadata.model_name}<div>
               <span class="muted">model</span>
-              {metadata.model_name}
+              <code>{metadata.model_name}</code>
             </div>{/if}
           {#if seed !== undefined}
             <div>
@@ -480,6 +525,13 @@
     max-width: 220px;
     margin-left: auto;
   }
+  .subfolderpick {
+    /* The global select rule is width: 100% - here it must share the row */
+    width: auto;
+    max-width: 200px;
+    font-family: var(--font-mono);
+    font-size: var(--t-sm);
+  }
   .picks {
     display: flex;
     flex-wrap: wrap;
@@ -547,7 +599,7 @@
        view, which is most of the win for cheap. contain-intrinsic-size
        keeps scrollbar height stable before a cell has ever been measured. */
     content-visibility: auto;
-    contain-intrinsic-size: 150px 180px;
+    contain-intrinsic-size: 150px 210px;
   }
   .cell:hover,
   .cell.active {
@@ -575,8 +627,17 @@
     padding: 0.35rem 0.5rem 0.4rem;
     border-top: 1px solid var(--line);
     overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+    /* Sibling outputs of one step share a long common prefix and differ only
+       near the end (the i.j.k index, or a dedupe counter right before the
+       extension) - a single nowrap+ellipsis line would hide exactly the part
+       that tells them apart, so wrap onto a few lines and break mid-token
+       instead of clipping. */
+    display: -webkit-box;
+    -webkit-line-clamp: 4;
+    line-clamp: 4;
+    -webkit-box-orient: vertical;
+    white-space: normal;
+    word-break: break-all;
   }
   .detail {
     position: sticky;
diff --git a/ui/src/lib/pages/GalleryPage.test.ts b/ui/src/lib/pages/GalleryPage.test.ts
index e4db9626..f4d6a810 100644
--- a/ui/src/lib/pages/GalleryPage.test.ts
+++ b/ui/src/lib/pages/GalleryPage.test.ts
@@ -12,10 +12,12 @@ import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 import GalleryPage from './GalleryPage.svelte'
 import ConfirmDialog from '../ConfirmDialog.svelte'
 import type { GalleryFile } from '../types'
+import { DEFAULT_WORKSPACE, workspace } from '../workspace.svelte'
 
-const file = (name: string): GalleryFile => ({
+const file = (name: string, subfolder = ''): GalleryFile => ({
   name,
   folder: name.includes('/') ? name.split('/')[0] : '',
+  subfolder,
   url: `/outputs/${name}`,
   kind: 'image',
   size: 1024,
@@ -57,7 +59,7 @@ const notifyError = vi.hoisted(() => vi.fn())
 vi.mock('../toast', () => ({ notify: { error: notifyError } }))
 
 beforeEach(() => {
-  listing.files = ['a.png', 'b.png', 'demo/c.png'].map(file)
+  listing.files = ['a.png', 'b.png', 'demo/c.png'].map((name) => file(name))
 })
 afterEach(() => {
   // Without this each render's DOM stays behind and the next test's
@@ -68,6 +70,7 @@ afterEach(() => {
   archiveOutputs.mockClear()
   notifyError.mockClear()
   vi.unstubAllGlobals()
+  workspace.current = DEFAULT_WORKSPACE
 })
 
 /** The grid's per-file selection checkbox. */
@@ -123,7 +126,9 @@ it('shift-clicking extends the selection across the range', async () => {
 })
 
 it('selects only the files the filter leaves visible', async () => {
-  listing.files = ['keep-a.png', 'keep-b.png', 'other.png'].map(file)
+  listing.files = ['keep-a.png', 'keep-b.png', 'other.png'].map((name) =>
+    file(name),
+  )
   await renderGallery('keep-a.png')
 
   const filter = screen.getByPlaceholderText('filter…') as HTMLInputElement
@@ -221,3 +226,137 @@ it('drops a file deleted from the detail panel out of the selection', async () =
   await waitFor(() => expect(screen.getByText('1 selected')).toBeTruthy())
   expect(screen.getByLabelText('select b.png')).toBeTruthy()
 })
+
+it('offers no subfolder control when nothing was written to one', async () => {
+  await renderGallery()
+  expect(screen.queryByRole('combobox', { name: 'subfolder' })).toBeNull()
+})
+
+it('lists the subfolders the outputs landed in and filters the grid by one', async () => {
+  listing.files = [
+    file('wf/run-1/final/deliverable.png', 'final'),
+    file('wf/run-1/intermediate/scratch.png', 'intermediate'),
+    file('wf/run-1/root.png', ''),
+  ]
+  await renderGallery('wf/run-1/final/deliverable.png')
+
+  const pick = screen.getByRole('combobox', {
+    name: 'subfolder',
+  }) as HTMLSelectElement
+  expect([...pick.options].map((o) => o.textContent?.trim())).toEqual([
+    'all subfolders',
+    '(run root)',
+    'final/',
+    'intermediate/',
+  ])
+
+  pick.value = 'final'
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  await waitFor(() =>
+    expect(
+      screen.queryByLabelText('select wf/run-1/intermediate/scratch.png'),
+    ).toBeNull(),
+  )
+  expect(
+    screen.getByLabelText('select wf/run-1/final/deliverable.png'),
+  ).toBeTruthy()
+  expect(screen.queryByLabelText('select wf/run-1/root.png')).toBeNull()
+  // Select all takes what the subfolder filter leaves showing
+  screen.getByRole('button', { name: /select all matching \(1\)/i }).click()
+  await waitFor(() => expect(screen.getByText('1 selected')).toBeTruthy())
+})
+
+it('intersects the subfolder pick with the text filter', async () => {
+  listing.files = [
+    file('wf/run-1/final/a.png', 'final'),
+    file('wf/run-1/final/b.png', 'final'),
+    file('wf/run-1/intermediate/a.png', 'intermediate'),
+  ]
+  await renderGallery('wf/run-1/final/a.png')
+
+  const pick = screen.getByRole('combobox', {
+    name: 'subfolder',
+  }) as HTMLSelectElement
+  pick.value = 'final'
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  const filter = screen.getByPlaceholderText('filter…') as HTMLInputElement
+  filter.value = '/a.'
+  filter.dispatchEvent(new Event('input', { bubbles: true }))
+
+  await waitFor(() =>
+    expect(screen.queryByLabelText('select wf/run-1/final/b.png')).toBeNull(),
+  )
+  expect(screen.getByLabelText('select wf/run-1/final/a.png')).toBeTruthy()
+  expect(
+    screen.queryByLabelText('select wf/run-1/intermediate/a.png'),
+  ).toBeNull()
+})
+
+it('falls back to every subfolder when the picked one empties out', async () => {
+  listing.files = [
+    file('wf/run-1/final/only.png', 'final'),
+    file('wf/run-1/root.png', ''),
+  ]
+  await renderGallery('wf/run-1/final/only.png')
+  const pick = screen.getByRole('combobox', {
+    name: 'subfolder',
+  }) as HTMLSelectElement
+  pick.value = 'final'
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  await waitFor(() =>
+    expect(screen.queryByLabelText('select wf/run-1/root.png')).toBeNull(),
+  )
+
+  checkbox('wf/run-1/final/only.png').click()
+  await waitFor(() => expect(screen.getByText('1 selected')).toBeTruthy())
+  screen.getByRole('button', { name: /^delete/i }).click()
+  await answerConfirm(true)
+
+  // The last final/ file is gone: the control goes with it and the grid
+  // shows everything again rather than an empty page pinned to a value
+  // that no longer exists
+  await waitFor(() =>
+    expect(screen.getByLabelText('select wf/run-1/root.png')).toBeTruthy(),
+  )
+  expect(screen.queryByRole('combobox', { name: 'subfolder' })).toBeNull()
+})
+
+it('resets a run-root pick when the control it depends on disappears', async () => {
+  listing.files = [
+    file('wf/run-1/final/only.png', 'final'),
+    file('wf/run-1/root.png', ''),
+  ]
+  await renderGallery('wf/run-1/final/only.png')
+  const pick = screen.getByRole('combobox', {
+    name: 'subfolder',
+  }) as HTMLSelectElement
+  // "all subfolders" and "(run root)" both carry the native value "" -
+  // Svelte tells them apart by each option's bound __value - so picking by
+  // index is what actually lands on "(run root)" rather than falling back
+  // to "all subfolders"
+  pick.selectedIndex = 1
+  pick.dispatchEvent(new Event('change', { bubbles: true }))
+  await waitFor(() =>
+    expect(
+      screen.queryByLabelText('select wf/run-1/final/only.png'),
+    ).toBeNull(),
+  )
+  expect(screen.getByLabelText('select wf/run-1/root.png')).toBeTruthy()
+
+  // The run-root pick has just hidden the only other file, so nothing in
+  // this grid's own checkboxes can reach it to delete it - a workspace
+  // switch stands in for that (or the same file being deleted from
+  // elsewhere): the listing comes back with no subfolder at all, the same
+  // shape the last foldered file's own deletion would leave behind
+  listing.files = [file('wf/run-1/root.png', '')]
+  workspace.current = 'other'
+  await waitFor(() => expect(gallery).toHaveBeenCalledTimes(2))
+
+  // The control goes with the pick it can no longer offer, and "Select
+  // all" reads as unfiltered again rather than sticking on a filter
+  // nothing can now clear
+  expect(screen.queryByRole('combobox', { name: 'subfolder' })).toBeNull()
+  expect(
+    screen.getByRole('button', { name: /^select all \(1\)$/i }),
+  ).toBeTruthy()
+})
diff --git a/ui/src/lib/pages/JobPage.svelte b/ui/src/lib/pages/JobPage.svelte
index afbfbf56..af543af6 100644
--- a/ui/src/lib/pages/JobPage.svelte
+++ b/ui/src/lib/pages/JobPage.svelte
@@ -6,13 +6,15 @@
     TriangleAlert,
     X,
   } from '@lucide/svelte'
+  import { untrack } from 'svelte'
   import { ApiError, api, outputUrl, streamJobEvents } from '../api'
   import { confirmDialog } from '../confirm.svelte'
   import { go } from '../router.svelte'
-  import { groupResultFiles } from '../results'
+  import { groupResultFiles, sectionBySubfolder } from '../results'
   import { stepProgress } from '../progress'
   import FlowView from '../editor/FlowView.svelte'
   import CopyButton from '../CopyButton.svelte'
+  import DownloadLink from '../DownloadLink.svelte'
   import { notify } from '../toast'
   import type { JobDetail, JobEvent } from '../types'
 
@@ -39,6 +41,9 @@
     events = []
     definition = null
     seedVariable = null
+    // Under the flat output layout two runs write the same file names, so
+    // a map keyed by name would show the last job's recipe for this one
+    fileMeta = {}
     // stopped guards the async gap: navigating away mid-fetch must not let
     // a late-resolving getJob open a stream nothing will ever stop
     let stopped = false
@@ -184,12 +189,63 @@
   const fileGroups = $derived(
     groupResultFiles(job?.manifest, events as JobEvent[]),
   )
+
+  /** A prompt argument as displayable text - pipelines accept a list too. */
+  function promptText(value: unknown): string {
+    if (typeof value === 'string') return value
+    if (Array.isArray(value))
+      return value.filter((v) => typeof v === 'string').join('\n')
+    return ''
+  }
+
+  // The generation metadata embedded in each image, keyed by file - per
+  // file rather than per step, since each image of a batch carries its own
+  // seed. Images only: the metadata route decodes an audio or video file
+  // whole to probe it, and nothing it would report is shown here. A key
+  // present with null is a lookup already in flight or failed
+  let fileMeta = $state<Record<string, Record<string, unknown> | null>>({})
+  $effect(() => {
+    const workspace = job?.workspace
+    const pending = fileGroups
+      .flatMap((group) => group.files)
+      .filter((file) => isImage(file) && !(file in untrack(() => fileMeta)))
+    if (!pending.length) return
+    untrack(() => {
+      for (const file of pending) {
+        fileMeta[file] = null
+        api
+          .galleryMetadata(file, workspace)
+          .then((r) => {
+            fileMeta[file] = r.metadata
+          })
+          .catch(() => {})
+      }
+    })
+  })
+
+  /** The gallery detail's fields for one output's embedded metadata. */
+  function describe(meta: Record<string, unknown> | null | undefined) {
+    const args =
+      (meta?.arguments as Record<string, unknown> | undefined) ?? null
+    return {
+      model: typeof meta?.model_name === 'string' ? meta.model_name : '',
+      seed: typeof meta?.seed === 'number' ? meta.seed : args?.seed,
+      prompt: promptText(args?.prompt),
+      negativePrompt: promptText(args?.negative_prompt),
+    }
+  }
   // Nothing at all was generated: every step the manifest lists was served
   // from the step cache. Worth saying outright - the page otherwise shows a
   // succeeded job full of images that are not this run's
   const allReused = $derived(
     fileGroups.length > 0 && fileGroups.every((group) => group.reused),
   )
+  // Sections by result.subfolder - one root section, no heading, when no
+  // step chose one, so an older run renders as it always did
+  const sections = $derived(sectionBySubfolder(fileGroups))
+  const sectioned = $derived(
+    sections.length > 1 || sections[0].subfolder !== '',
+  )
   const running = $derived(job !== null && !TERMINAL.includes(job.status))
   // A cancel requested while loading a model or running a task step has no
   // checkpoint to catch it until that phase finishes - without this the UI
@@ -354,42 +410,86 @@
             Use <strong>New seed</strong> for a different image.{/if}
         </p>
       {/if}
-      {#each fileGroups as group (group.step)}
-        {#if fileGroups.length > 1}
-          <h3 class="stephead muted">
-            {group.step}
-            {#if group.reused && !allReused}
-              <span
-                class="muted"
-                title="served from the step cache - an
-                     earlier run's files, nothing generated for this step"
-                >· reused</span
-              >
-            {/if}
+      {#each sections as section (section.subfolder)}
+        {#if sectioned}
+          <h3 class="subhead">
+            {section.subfolder === '' ? '(run root)' : `${section.subfolder}/`}
           </h3>
         {/if}
-        <div class="media">
+        {#each section.groups as group (group.step)}
+          {#if fileGroups.length > 1}
+            <svelte:element
+              this={sectioned ? 'h4' : 'h3'}
+              class="stephead muted"
+            >
+              {group.step}
+              {#if group.reused && !allReused}
+                <span
+                  class="muted"
+                  title="served from the step cache - an
+                       earlier run's files, nothing generated for this step"
+                  >· reused</span
+                >
+              {/if}
+            </svelte:element>
+          {/if}
           {#each group.files as file (file)}
-            {#if isImage(file)}
-              <a
-                class="frame plain"
-                href={fileUrl(file)}
-                target="_blank"
-                title={file.split('/').pop()}
-                ><img src={fileUrl(file)} alt={file.split('/').pop()} /></a
-              >
-            {:else if isVideo(file)}
-              <span class="frame">
-                <!-- svelte-ignore a11y_media_has_caption -->
-                <video src={fileUrl(file)} controls loop></video>
-              </span>
-            {:else}
-              <a class="filelink" href={fileUrl(file)} target="_blank"
-                >{file.split('/').pop()}</a
-              >
-            {/if}
+            {@const info = describe(fileMeta[file])}
+            <!-- Laid out as the gallery detail is: the media on the left,
+                 what made it on the right -->
+            <div class="output">
+              {#if isImage(file)}
+                <a
+                  class="frame plain"
+                  href={fileUrl(file)}
+                  target="_blank"
+                  title={file.split('/').pop()}
+                  ><img src={fileUrl(file)} alt={file.split('/').pop()} /></a
+                >
+              {:else if isVideo(file)}
+                <span class="frame">
+                  <!-- svelte-ignore a11y_media_has_caption -->
+                  <video src={fileUrl(file)} controls loop></video>
+                </span>
+              {:else}
+                <a class="filelink" href={fileUrl(file)} target="_blank"
+                  >{file.split('/').pop()}</a
+                >
+              {/if}
+              <div class="meta">
+                <div class="metabar">
+                  <span class="filename">{file.split('/').pop()}</span>
+                  <DownloadLink
+                    href={api.outputDownloadUrl(file, job.workspace)}
+                  />
+                </div>
+                {#if info.model}
+                  <div>
+                    <span class="muted">model</span>
+                    <code>{info.model}</code>
+                  </div>
+                {/if}
+                {#if info.seed !== undefined}
+                  <div>
+                    <span class="muted">seed</span> <code>{info.seed}</code>
+                  </div>
+                {/if}
+                {#if info.prompt}
+                  <div class="prompt">
+                    <span class="muted">prompt</span>
+                    <p>{info.prompt}</p>
+                  </div>
+                {/if}
+                {#if info.negativePrompt}
+                  <div class="prompt">
+                    <span class="muted">negative prompt</span>
+                    <p>{info.negativePrompt}</p>
+                  </div>
+                {/if}
+              </div>
+            </div>
           {/each}
-        </div>
+        {/each}
       {/each}
     </div>
   {/if}
@@ -502,28 +602,68 @@
     font-variant-numeric: tabular-nums;
     font-size: 0.8rem;
   }
-  .media {
+  /* One output per row, the gallery detail's shape: the proof on the left,
+     the recipe that made it on the right */
+  .output {
     display: flex;
-    flex-wrap: wrap;
-    gap: var(--space-2);
+    gap: var(--space-4);
     align-items: flex-start;
+    flex-wrap: wrap;
+  }
+  .output + .output {
+    margin-top: var(--space-3);
+    padding-top: var(--space-3);
+    border-top: 1px solid var(--line);
   }
   /* What the run produced, framed the way the catalog and the gallery
      frame it - the picture flush to its edges, no rounding of its own */
-  .media :global(.frame) {
-    max-width: min(340px, 100%);
+  .output :global(.frame) {
+    max-width: min(480px, 100%);
   }
-  .media :global(.frame > video) {
+  .output :global(.frame > video) {
     height: auto;
   }
-  .media a.filelink {
+  .output a.filelink {
+    font-family: var(--font-mono);
+    font-size: var(--t-sm);
+  }
+  .meta {
+    display: flex;
+    flex-direction: column;
+    gap: 0.2rem;
+    font-size: 0.85rem;
+    max-width: 46ch;
+    min-width: 0;
+  }
+  .meta .muted {
+    margin-right: 0.4rem;
+  }
+  .metabar {
+    display: flex;
+    align-items: center;
+    gap: 0.8rem;
+    margin-bottom: 0.3rem;
+  }
+  /* The name the engine wrote, and what you would type to reference it */
+  .filename {
     font-family: var(--font-mono);
     font-size: var(--t-sm);
+    overflow-wrap: anywhere;
+    flex: 1;
+  }
+  .prompt p {
+    margin: 0.15rem 0 0;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
   }
   .error {
     color: var(--bad);
   }
   .stephead {
+    font-family: var(--font-mono);
+    font-weight: 600;
+    line-height: 1.15;
+    letter-spacing: -0.01em;
     font-size: 0.78rem;
     text-transform: none;
     margin: var(--space-3) 0 var(--space-2);
@@ -531,4 +671,15 @@
   .stephead:first-of-type {
     margin-top: 0;
   }
+  .subhead {
+    font-size: var(--t-sm);
+    text-transform: none;
+    margin: var(--space-3) 0 var(--space-1);
+  }
+  .subhead:first-of-type {
+    margin-top: 0;
+  }
+  .subhead + .stephead {
+    margin-top: 0;
+  }
 </style>
diff --git a/ui/src/lib/pages/JobPage.test.ts b/ui/src/lib/pages/JobPage.test.ts
new file mode 100644
index 00000000..84a20d16
--- /dev/null
+++ b/ui/src/lib/pages/JobPage.test.ts
@@ -0,0 +1,151 @@
+import { cleanup, render, screen, waitFor } from '@testing-library/svelte'
+import { afterEach, expect, it, vi } from 'vitest'
+import JobPage from './JobPage.svelte'
+import { api } from '../api'
+import type { JobDetail, JobEvent } from '../types'
+
+const detail = vi.hoisted(() => ({ job: null as JobDetail | null }))
+// The live stream's callback, captured so a test can push step_end events
+const stream = vi.hoisted(() => ({
+  onEvent: null as ((event: JobEvent) => void) | null,
+}))
+// What the metadata route answers for each file, by name
+const metadata = vi.hoisted(() => ({
+  byFile: {} as Record<string, Record<string, unknown>>,
+}))
+
+vi.mock('../api', () => ({
+  ApiError: class ApiError extends Error {},
+  api: {
+    getJob: vi.fn(() => Promise.resolve(detail.job)),
+    getJobWorkflow: vi.fn(() =>
+      Promise.resolve({ definition: null, seed_variable: null }),
+    ),
+    galleryMetadata: vi.fn((name: string) =>
+      Promise.resolve({
+        name,
+        metadata: metadata.byFile[name] ?? null,
+        job: null,
+      }),
+    ),
+    outputDownloadUrl: (name: string) => `/api/gallery/${name}/download`,
+  },
+  outputUrl: (path: string) => `/outputs/${path}`,
+  streamJobEvents: (
+    _jobId: string,
+    _after: number,
+    onEvent: (event: JobEvent) => void,
+  ) => {
+    stream.onEvent = onEvent
+    return () => {}
+  },
+}))
+vi.mock('../toast', () => ({ notify: { error: vi.fn(), success: vi.fn() } }))
+
+const job = (manifest: JobDetail['manifest']): JobDetail => ({
+  id: 'j1',
+  workflow: 'templates/minimax/storyboard',
+  status: 'succeeded',
+  created_at: 1,
+  started_at: 1,
+  finished_at: 2,
+  workspace: 'default',
+  arguments: {},
+  warnings: [],
+  manifest,
+  error: null,
+  traceback: null,
+  event_count: 0,
+})
+
+afterEach(() => {
+  cleanup()
+  stream.onEvent = null
+  metadata.byFile = {}
+  vi.mocked(api.galleryMetadata).mockClear()
+})
+
+it('shows each image beside what made it, with a download link, and never probes a video', async () => {
+  metadata.byFile['a.png'] = {
+    model_name: 'org/model',
+    seed: 7,
+    arguments: { prompt: 'a cat', negative_prompt: 'a dog' },
+  }
+  detail.job = job([{ step: 'generate', files: ['a.png', 'clip.mp4'] }])
+  render(JobPage, { jobId: 'j1' })
+  await waitFor(() => expect(screen.getByText('org/model')).toBeTruthy())
+  expect(screen.getByText('7')).toBeTruthy()
+  expect(screen.getByText('a cat')).toBeTruthy()
+  expect(screen.getByText('a dog')).toBeTruthy()
+  expect(
+    screen
+      .getAllByRole('link', { name: 'Download' })
+      .map((a) => a.getAttribute('href')),
+  ).toEqual(['/api/gallery/a.png/download', '/api/gallery/clip.mp4/download'])
+  // The metadata route decodes a video whole to probe it, and the page
+  // shows nothing a probe would report
+  expect(vi.mocked(api.galleryMetadata).mock.calls.map((c) => c[0])).toEqual([
+    'a.png',
+  ])
+})
+
+it('groups a foldered run under final/ and intermediate/ headings, final first', async () => {
+  detail.job = job([
+    {
+      step: 'board_1',
+      files: ['intermediate/b1.png'],
+      subfolder: 'intermediate',
+    },
+    { step: 'voyage', files: ['final/voyage.mp4'], subfolder: 'final' },
+  ])
+  render(JobPage, { jobId: 'j1' })
+  const headings = await waitFor(() => {
+    const found = screen.getAllByRole('heading', { level: 3 })
+    expect(found.length).toBeGreaterThanOrEqual(2)
+    return found
+  })
+  expect(headings.map((h) => h.textContent?.trim())).toEqual([
+    'final/',
+    'intermediate/',
+  ])
+  // Step names drop to h4 under a subfolder heading
+  expect(
+    screen
+      .getAllByRole('heading', { level: 4 })
+      .map((h) => h.textContent?.trim()),
+  ).toEqual(['voyage', 'board_1'])
+})
+
+it('renders an unfoldered run exactly as before: step headings, no subfolder heading', async () => {
+  detail.job = job([
+    { step: 'generate', files: ['a.png'] },
+    { step: 'upscale', files: ['a_big.png'], subfolder: '' },
+  ])
+  render(JobPage, { jobId: 'j1' })
+  await waitFor(() => expect(screen.getByText('upscale')).toBeTruthy())
+  expect(
+    screen
+      .getAllByRole('heading', { level: 3 })
+      .map((h) => h.textContent?.trim()),
+  ).toEqual(['generate', 'upscale'])
+  expect(screen.queryByRole('heading', { level: 4 })).toBeNull()
+  expect(screen.queryByText('(run root)')).toBeNull()
+})
+
+it('places a live step_end under its subfolder before the manifest arrives', async () => {
+  detail.job = { ...job([]), status: 'running', finished_at: null }
+  render(JobPage, { jobId: 'j1' })
+  await waitFor(() => expect(stream.onEvent).not.toBeNull())
+  stream.onEvent!({
+    seq: 1,
+    event: 'step_end',
+    step: 'episode',
+    files: ['final/e.mp4'],
+    subfolder: 'final',
+  })
+  await waitFor(() =>
+    expect(
+      screen.getByRole('heading', { level: 3, name: 'final/' }),
+    ).toBeTruthy(),
+  )
+})
diff --git a/ui/src/lib/results.test.ts b/ui/src/lib/results.test.ts
index 68aa9452..681eddd1 100644
--- a/ui/src/lib/results.test.ts
+++ b/ui/src/lib/results.test.ts
@@ -1,9 +1,21 @@
 import { describe, expect, it } from 'vitest'
-import { groupResultFiles } from './results'
+import { groupResultFiles, sectionBySubfolder } from './results'
 import type { JobEvent } from './types'
 
-const stepEnd = (step: string, files: string[]): JobEvent =>
-  ({ seq: 0, event: 'step_end', step, files }) as unknown as JobEvent
+const stepEnd = (
+  step: string,
+  files: string[],
+  subfolder?: string,
+  reused?: boolean,
+): JobEvent =>
+  ({
+    seq: 0,
+    event: 'step_end',
+    step,
+    files,
+    subfolder,
+    reused,
+  }) as unknown as JobEvent
 
 describe('groupResultFiles', () => {
   it('groups streamed files by producing step, in completion order', () => {
@@ -12,8 +24,13 @@ describe('groupResultFiles', () => {
       stepEnd('upscale', ['a_big.png']),
     ])
     expect(groups).toEqual([
-      { step: 'generate', files: ['a.png', 'b.png'], reused: false },
-      { step: 'upscale', files: ['a_big.png'], reused: false },
+      {
+        step: 'generate',
+        files: ['a.png', 'b.png'],
+        reused: false,
+        subfolder: '',
+      },
+      { step: 'upscale', files: ['a_big.png'], reused: false, subfolder: '' },
     ])
   })
 
@@ -23,7 +40,12 @@ describe('groupResultFiles', () => {
       [stepEnd('generate', ['a.png'])],
     )
     expect(groups).toEqual([
-      { step: 'generate', files: ['a.png', 'c.png'], reused: false },
+      {
+        step: 'generate',
+        files: ['a.png', 'c.png'],
+        reused: false,
+        subfolder: '',
+      },
     ])
   })
 
@@ -36,7 +58,7 @@ describe('groupResultFiles', () => {
       [],
     )
     expect(groups).toEqual([
-      { step: 'generate', files: ['a.png'], reused: false },
+      { step: 'generate', files: ['a.png'], reused: false, subfolder: '' },
     ])
   })
 
@@ -50,4 +72,91 @@ describe('groupResultFiles', () => {
     )
     expect(groups.map((g) => g.reused)).toEqual([true, false])
   })
+
+  it('reads reused live from step_end before any manifest arrives', () => {
+    const groups = groupResultFiles(undefined, [
+      stepEnd('generate', ['a.png'], undefined, true),
+    ])
+    expect(groups[0].reused).toBe(true)
+  })
+})
+
+describe('groupResultFiles subfolder', () => {
+  it('places a group from the live step_end and lets the manifest confirm it', () => {
+    const groups = groupResultFiles(
+      [{ step: 'episode', files: ['final/e.mp4'], subfolder: 'final' }],
+      [stepEnd('episode', ['final/e.mp4'], 'final')],
+    )
+    expect(groups).toEqual([
+      {
+        step: 'episode',
+        files: ['final/e.mp4'],
+        reused: false,
+        subfolder: 'final',
+      },
+    ])
+  })
+
+  it('reads the subfolder from the stream alone while the job runs', () => {
+    const groups = groupResultFiles(undefined, [
+      stepEnd('shot', ['intermediate/s.mp4'], 'intermediate'),
+    ])
+    expect(groups[0].subfolder).toBe('intermediate')
+  })
+
+  it('treats a manifest entry without the field as the run root', () => {
+    const groups = groupResultFiles([{ step: 'old', files: ['a.png'] }], [])
+    expect(groups[0].subfolder).toBe('')
+  })
+
+  it('lets the manifest win when it names a different subfolder', () => {
+    const groups = groupResultFiles(
+      [{ step: 's', files: ['final/x.png'], subfolder: 'final' }],
+      [stepEnd('s', ['final/x.png'], '')],
+    )
+    expect(groups[0].subfolder).toBe('final')
+  })
+})
+
+describe('sectionBySubfolder', () => {
+  const group = (step: string, subfolder: string) => ({
+    step,
+    files: [`${subfolder ? subfolder + '/' : ''}${step}.png`],
+    reused: false,
+    subfolder,
+  })
+
+  it('returns one root section when no group has a subfolder', () => {
+    const sections = sectionBySubfolder([group('a', ''), group('b', '')])
+    expect(sections).toEqual([
+      { subfolder: '', groups: [group('a', ''), group('b', '')] },
+    ])
+  })
+
+  it('returns one root section for no groups at all', () => {
+    expect(sectionBySubfolder([])).toEqual([{ subfolder: '', groups: [] }])
+  })
+
+  it('sections by subfolder in first-appearance order, final first', () => {
+    const sections = sectionBySubfolder([
+      group('draw', 'intermediate'),
+      group('shot', 'intermediate'),
+      group('episode', 'final'),
+      group('notes', ''),
+    ])
+    expect(sections.map((s) => s.subfolder)).toEqual([
+      'final',
+      'intermediate',
+      '',
+    ])
+    expect(sections[1].groups.map((g) => g.step)).toEqual(['draw', 'shot'])
+  })
+
+  it('keeps any name the engine accepted, not just the convention', () => {
+    const sections = sectionBySubfolder([
+      group('a', 'shots/act-1'),
+      group('b', 'final'),
+    ])
+    expect(sections.map((s) => s.subfolder)).toEqual(['final', 'shots/act-1'])
+  })
 })
diff --git a/ui/src/lib/results.ts b/ui/src/lib/results.ts
index 9644c725..c84e946c 100644
--- a/ui/src/lib/results.ts
+++ b/ui/src/lib/results.ts
@@ -1,4 +1,13 @@
-import type { JobEvent, ManifestEntry } from './types'
+import type { JobEvent, ManifestEntry, StepEndEvent } from './types'
+
+/** One step's output files, with where in the run directory they landed. */
+export interface StepGroup {
+  step: string
+  files: string[]
+  reused: boolean
+  /** The step's `result.subfolder` - `''` for the run root. */
+  subfolder: string
+}
 
 /** A run's output files, grouped by the step that produced them. The
  * step_end stream carries the association live; the manifest confirms it
@@ -7,30 +16,33 @@ import type { JobEvent, ManifestEntry } from './types'
 export function groupResultFiles(
   manifest: ManifestEntry[] | undefined,
   events: JobEvent[],
-): Array<{ step: string; files: string[]; reused: boolean }> {
+): StepGroup[] {
   const order: string[] = []
   const byStep = new Map<string, Set<string>>()
-  // Only the manifest knows a step was served from the step cache; the
-  // live step_end stream carries files but not that flag
+  // The engine reports a step served from the step cache on the live
+  // step_end stream, and again on the manifest
   const reused = new Set<string>()
-  const add = (step: string, files: string[]) => {
+  // Placed by the live step_end, confirmed by the manifest - the manifest
+  // is written last, so its value is the one that stands
+  const subfolder = new Map<string, string>()
+  const add = (step: string, files: string[], where: string | undefined) => {
     if (!byStep.has(step)) {
       byStep.set(step, new Set())
       order.push(step)
     }
     const set = byStep.get(step)!
     for (const file of files) set.add(file)
+    if (where !== undefined) subfolder.set(step, where)
   }
   for (const event of events) {
     if (event.event === 'step_end') {
-      add(
-        (event.step as string) || '(unnamed)',
-        (event.files as string[]) ?? [],
-      )
+      const end = event as StepEndEvent
+      add(end.step || '(unnamed)', end.files ?? [], end.subfolder)
+      if (end.reused) reused.add(end.step || '(unnamed)')
     }
   }
   for (const entry of manifest ?? []) {
-    add(entry.step, entry.files)
+    add(entry.step, entry.files, entry.subfolder ?? '')
     if (entry.reused) reused.add(entry.step)
   }
   return order
@@ -38,6 +50,39 @@ export function groupResultFiles(
       step,
       files: [...byStep.get(step)!],
       reused: reused.has(step),
+      subfolder: subfolder.get(step) ?? '',
     }))
     .filter((group) => group.files.length > 0)
 }
+
+/** The step groups of one subfolder, under one heading on the job page. */
+export interface SubfolderSection {
+  subfolder: string
+  groups: StepGroup[]
+}
+
+/** Step groups sectioned by the subfolder they landed in. A run where no
+ * step chose one is a single root section, so the page renders as it did
+ * before the field existed. Otherwise sections follow first appearance,
+ * except `final` leads: by convention it is the deliverable, the thing the
+ * page was opened for. The engine treats no name specially - any other
+ * value is a section like the rest. */
+export function sectionBySubfolder(groups: StepGroup[]): SubfolderSection[] {
+  const order: string[] = []
+  const bySubfolder = new Map<string, StepGroup[]>()
+  for (const group of groups) {
+    if (!bySubfolder.has(group.subfolder)) {
+      bySubfolder.set(group.subfolder, [])
+      order.push(group.subfolder)
+    }
+    bySubfolder.get(group.subfolder)!.push(group)
+  }
+  if (order.every((s) => s === '')) return [{ subfolder: '', groups }]
+  const ordered = order.includes('final')
+    ? ['final', ...order.filter((s) => s !== 'final')]
+    : order
+  return ordered.map((subfolder) => ({
+    subfolder,
+    groups: bySubfolder.get(subfolder)!,
+  }))
+}
diff --git a/ui/src/lib/types.ts b/ui/src/lib/types.ts
index 1f6d1353..8f370c18 100644
--- a/ui/src/lib/types.ts
+++ b/ui/src/lib/types.ts
@@ -17,6 +17,10 @@ export interface ManifestEntry {
   /** The step was served from the step cache: these files are an earlier
    * run's, republished, and nothing was generated for them this time. */
   reused?: boolean
+  /** The in-run subfolder the step's `result.subfolder` chose - `final`,
+   * `intermediate`, any relative path - `''` when it chose none. Absent
+   * only on a job recorded before the field existed. */
+  subfolder?: string
 }
 
 export interface JobDetail extends JobSummary {
@@ -34,6 +38,16 @@ export interface JobEvent {
   [key: string]: unknown
 }
 
+/** The `step_end` event, as the job page reads it: what the step saved and
+ * where, before the manifest confirms it. */
+export interface StepEndEvent extends JobEvent {
+  event: 'step_end'
+  step: string
+  files?: string[]
+  subfolder?: string
+  reused?: boolean
+}
+
 export interface HealthInfo {
   status: string
   version?: string
@@ -198,6 +212,9 @@ export interface ValidationResult {
 export interface GalleryFile {
   name: string
   folder: string
+  /** What followed the run id in the file's path - the `final` /
+   * `intermediate` a step's `result.subfolder` chose, `''` for none. */
+  subfolder: string
   url: string
   kind: 'image' | 'video' | 'audio'
   size: number
diff --git a/workflows/templates/assemble-and-score.json b/workflows/templates/assemble-and-score.json
index 0f45c9b8..932eca2c 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.",
+    "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.",
     "cost": [
         {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 0.2}
     ],
@@ -15,6 +15,7 @@
         "fps": 24,
         "audio_bleed_ms": 0,
         "seam_fade_ms": null,
+        "match_levels": null,
         "score_start_frame": 0,
         "total_frames": 360,
         "score_gain": 1.0,
@@ -29,7 +30,8 @@
                     "videos": "variable:shots",
                     "fps": "variable:fps",
                     "audio_bleed_ms": "variable:audio_bleed_ms",
-                    "seam_fade_ms": "variable:seam_fade_ms"
+                    "seam_fade_ms": "variable:seam_fade_ms",
+                    "match_levels": "variable:match_levels"
                 }
             }
         },
diff --git a/workflows/templates/compose-workflows.json b/workflows/templates/compose-workflows.json
index 32fd695c..ff2b4e3d 100644
--- a/workflows/templates/compose-workflows.json
+++ b/workflows/templates/compose-workflows.json
@@ -25,7 +25,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -39,7 +40,8 @@
                 }
             },
             "result": {
-                "content_type": "video/mp4"
+                "content_type": "video/mp4",
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/consistent-set.json b/workflows/templates/consistent-set.json
index 4ed5b85d..11d1abaa 100644
--- a/workflows/templates/consistent-set.json
+++ b/workflows/templates/consistent-set.json
@@ -38,7 +38,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -61,7 +62,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -84,7 +86,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -107,7 +110,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/controlnet.json b/workflows/templates/controlnet.json
index 2d913bd8..98a3c9d6 100644
--- a/workflows/templates/controlnet.json
+++ b/workflows/templates/controlnet.json
@@ -18,7 +18,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -42,7 +43,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/describe-and-regenerate.json b/workflows/templates/describe-and-regenerate.json
index 19fba6c7..a1f3a7f8 100644
--- a/workflows/templates/describe-and-regenerate.json
+++ b/workflows/templates/describe-and-regenerate.json
@@ -30,7 +30,8 @@
                 }
             },
             "result": {
-                "content_type": "text/plain"
+                "content_type": "text/plain",
+                "subfolder": "intermediate"
             },
             "release_models": true
         },
@@ -46,7 +47,8 @@
                 }
             },
             "result": {
-                "content_type": "text/plain"
+                "content_type": "text/plain",
+                "subfolder": "intermediate"
             },
             "release_models": true
         },
@@ -61,7 +63,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/image-processors.json b/workflows/templates/image-processors.json
index a6a69910..43f071a4 100644
--- a/workflows/templates/image-processors.json
+++ b/workflows/templates/image-processors.json
@@ -24,7 +24,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -37,7 +38,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -50,7 +52,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -63,7 +66,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -76,7 +80,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -89,7 +94,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -102,7 +108,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -115,7 +122,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -128,7 +136,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -141,7 +150,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -154,7 +164,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -167,7 +178,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -180,7 +192,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -193,7 +206,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -206,7 +220,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -219,7 +234,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -232,7 +248,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -245,7 +262,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -258,7 +276,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -271,7 +290,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -284,7 +304,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -299,7 +320,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -313,7 +335,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -326,7 +349,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -341,7 +365,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/lora-styles.json b/workflows/templates/lora-styles.json
index 1845f63c..8bb2f158 100644
--- a/workflows/templates/lora-styles.json
+++ b/workflows/templates/lora-styles.json
@@ -40,7 +40,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -72,7 +73,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -104,7 +106,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -136,7 +139,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -168,7 +172,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -200,7 +205,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -232,7 +238,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -264,7 +271,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -296,7 +304,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         },
         {
@@ -328,7 +337,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/ltx2/generative-upscale.json b/workflows/templates/ltx2/generative-upscale.json
index cc045508..748a3626 100644
--- a/workflows/templates/ltx2/generative-upscale.json
+++ b/workflows/templates/ltx2/generative-upscale.json
@@ -134,7 +134,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -225,7 +226,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/minimax/dialogue-short.json b/workflows/templates/minimax/dialogue-short.json
index c0fbe45f..4427da76 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.",
+    "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.",
     "summary": "A multi-shot dialogue short: Z-Image draws the cast, each shot is generated fresh from the same portraits, then cut.",
     "cost": [
         {
@@ -112,6 +112,7 @@
         "subject_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference",
         "audio_bleed_ms": 1800,
         "seam_fade_ms": null,
+        "match_levels": null,
         "width": 960,
         "height": 544,
         "num_inference_steps": 9,
@@ -145,7 +146,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -171,7 +173,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -300,7 +303,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -312,12 +316,14 @@
                     "trim_frames": 0,
                     "audio_bleed_ms": "variable:audio_bleed_ms",
                     "fps": 24,
-                    "seam_fade_ms": "variable:seam_fade_ms"
+                    "seam_fade_ms": "variable:seam_fade_ms",
+                    "match_levels": "variable:match_levels"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/minimax/enhance-prompt-with-image.json b/workflows/templates/minimax/enhance-prompt-with-image.json
index 40b05a8a..3d2b3e89 100644
--- a/workflows/templates/minimax/enhance-prompt-with-image.json
+++ b/workflows/templates/minimax/enhance-prompt-with-image.json
@@ -33,7 +33,8 @@
                 }
             },
             "result": {
-                "content_type": "text/plain"
+                "content_type": "text/plain",
+                "subfolder": "intermediate"
             }
         },
         {
@@ -161,7 +162,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/minimax/enhance-prompt.json b/workflows/templates/minimax/enhance-prompt.json
index c691a92a..fbd513a7 100644
--- a/workflows/templates/minimax/enhance-prompt.json
+++ b/workflows/templates/minimax/enhance-prompt.json
@@ -30,7 +30,8 @@
                 }
             },
             "result": {
-                "content_type": "text/plain"
+                "content_type": "text/plain",
+                "subfolder": "intermediate"
             }
         },
         {
@@ -157,7 +158,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/minimax/generated-subject-reference.json b/workflows/templates/minimax/generated-subject-reference.json
index 051dfa55..2953ff77 100644
--- a/workflows/templates/minimax/generated-subject-reference.json
+++ b/workflows/templates/minimax/generated-subject-reference.json
@@ -35,7 +35,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -164,7 +165,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/minimax/music-video.json b/workflows/templates/minimax/music-video.json
index db77fad6..71c64838 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 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.",
+    "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 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.",
     "cost": [
         {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 35}
     ],
@@ -38,6 +38,7 @@
         "fps": 24,
         "audio_bleed_ms": 0,
         "seam_fade_ms": null,
+        "match_levels": null,
         "width": 960,
         "height": 544,
         "num_inference_steps": 9,
@@ -72,7 +73,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -100,7 +102,8 @@
             },
             "result": {
                 "content_type": "audio/mp3",
-                "sample_rate": 44100
+                "sample_rate": 44100,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -266,7 +269,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -278,7 +282,8 @@
                     "trim_frames": 0,
                     "fps": "variable:fps",
                     "audio_bleed_ms": "variable:audio_bleed_ms",
-                    "seam_fade_ms": "variable:seam_fade_ms"
+                    "seam_fade_ms": "variable:seam_fade_ms",
+                    "match_levels": "variable:match_levels"
                 }
             }
         },
@@ -294,7 +299,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/minimax/storyboard.json b/workflows/templates/minimax/storyboard.json
index 8773feab..6209d8af 100644
--- a/workflows/templates/minimax/storyboard.json
+++ b/workflows/templates/minimax/storyboard.json
@@ -45,7 +45,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -70,7 +71,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -96,7 +98,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -240,7 +243,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/qr-code.json b/workflows/templates/qr-code.json
index bd74ed19..6138c10f 100644
--- a/workflows/templates/qr-code.json
+++ b/workflows/templates/qr-code.json
@@ -16,7 +16,8 @@
                 },
                 "result": {
                     "content_type": "image/jpeg",
-                    "embed_metadata": true
+                    "embed_metadata": true,
+                    "subfolder": "intermediate"
                 }
             },
             {
@@ -31,7 +32,8 @@
                 },
                 "result": {
                     "content_type": "image/jpeg",
-                    "embed_metadata": true
+                    "embed_metadata": true,
+                    "subfolder": "intermediate"
                 }
             },
             {
@@ -68,7 +70,8 @@
                 },
                 "result": {
                     "content_type": "image/jpeg",
-                    "embed_metadata": true
+                    "embed_metadata": true,
+                    "subfolder": "final"
                 }
             }
         ]
diff --git a/workflows/templates/recenter-crop.json b/workflows/templates/recenter-crop.json
index 01464c9f..c18f19c8 100644
--- a/workflows/templates/recenter-crop.json
+++ b/workflows/templates/recenter-crop.json
@@ -29,7 +29,8 @@
                 }
             },
             "result": {
-                "content_type": "image/jpeg"
+                "content_type": "image/jpeg",
+                "subfolder": "final"
             }
         },
         {
@@ -46,7 +47,8 @@
                 }
             },
             "result": {
-                "content_type": "image/jpeg"
+                "content_type": "image/jpeg",
+                "subfolder": "final"
             }
         },
         {
@@ -64,7 +66,8 @@
                 }
             },
             "result": {
-                "content_type": "image/jpeg"
+                "content_type": "image/jpeg",
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/restore-faces.json b/workflows/templates/restore-faces.json
index 84ea1e32..22d3afa0 100644
--- a/workflows/templates/restore-faces.json
+++ b/workflows/templates/restore-faces.json
@@ -34,7 +34,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -50,7 +51,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/segment-and-inpaint.json b/workflows/templates/segment-and-inpaint.json
index bc409b87..0a18b16b 100644
--- a/workflows/templates/segment-and-inpaint.json
+++ b/workflows/templates/segment-and-inpaint.json
@@ -33,7 +33,8 @@
             "result": {
                 "content_type": "image/png",
                 "embed_metadata": true,
-                "save": true
+                "save": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -60,7 +61,8 @@
             },
             "result": {
                 "content_type": "image/png",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/sub-workflow.json b/workflows/templates/sub-workflow.json
index 20a03f76..90803eca 100644
--- a/workflows/templates/sub-workflow.json
+++ b/workflows/templates/sub-workflow.json
@@ -16,7 +16,8 @@
             },
             "result": {
                 "content_type": "image/jpeg",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "intermediate"
             }
         },
         {
@@ -29,7 +30,8 @@
             },
             "result": {
                 "content_type": "image/png",
-                "embed_metadata": true
+                "embed_metadata": true,
+                "subfolder": "final"
             }
         }
     ]