wicked-garden 12.41.0 → 12.43.0

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.41.0"}], "version": "12.41.0"}
+{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.43.0"}], "version": "12.43.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.41.0",
+  "version": "12.43.0",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 the wicked-estate code graph + injected bus/dispatch/capability/archetype edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory + knowledge (the mem domain over wicked-estate), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (the in-catalog qe domain). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault, a self-contained infra peer wicked-garden installs directly; wicked-bus is an opt-in layer \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_vault_version": "^0.5.0",
   "wicked_ledger_version": "^0.4.0",

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [12.43.0] — 2026-10-05
+
+### Fixed
+- **Walkthrough tool: the proof root is what crew's walkthrough view and acceptance read (wicked-garden#1208).** `scripts/demo/walkthrough.mjs record` wrote only `{key, verdict, failed_at_sec}` per chapter, `progress.json` only at the end, its segments under `<root>/segments/`, no planned chapter list and no stitched take — so crew's view (`GET /runs/:id/walkthrough`, WT-W1) showed "Starting the app" for the whole recording, then a failed chapter by its key with no title, no check, no frame and nothing to watch. The tool now writes crew's contract: `chapters.json` (`{key, title, blurb, tags, resets}`) before the app starts; `progress.json` `{state: "starting_app"}` → `{state: "recording", chapter, index, total}` per chapter → `{state: "judging"}`; `result.json` with a top-level `tree` and per chapter `title`, `takes`, `failed_at_sec` (the earliest failing check's `at_sec`, else the take's `failure.json` — DES §4.5), `failed_frame` (the earliest failing on-screen check's frame, else one cut from the take at `failed_at_sec`), `proves`, `legs` and `checks[] {id, kind, sentence, passed, at_sec, evidence[] (root-relative paths), vault_entry, detail}`; the segments under `demo-video/segments/<key>/`, and the take stitched from each chapter's kept video (the good take, else the failed take the recorder kept) into `demo-video/demo.mp4` with `demo-video/chapters.md` markers and `demo-video/poster.jpg`. **The seal is now the form crew recomputes** (`walkthrough-acceptance.ts`, WT-W2): sha256 over `"<sha256 hex>  <posix relative path>\n"` lines in UTF-8 byte order — the tool hashed `"<path>:<sha>\n"` in locale order, so every live take would have been denied as "walkthrough evidence changed after it was sealed". Like crew, the seal refuses a root holding a link or a non-regular entry outside `app/`/`data/`, or a file it cannot read: `record` then writes `INCONCLUSIVE` with `cause: unsealable_root` and prints the seal line with `bundle_sha: null` (crew reads it as not sealed and denies); `seal --root` exits 1 and says why. A chapter whose take failed has its kept video published at `demo-video/segments/<key>/segment.mp4` too (a copy; `guard.json` and `failed-<take>/failure.json` still say it failed), since that is the one path crew reads a chapter as recorded from. A segment key outside `^[a-z0-9][a-z0-9-]*$` (what `record.mjs` and crew accept) is refused as `storyline_refused`, naming the key, instead of being dropped by the view silently. `record.mjs` exports `stitchParts` (the one stitch, also used by its own `--stitch`) and `extractFrame`. Tests: `tests/demo/test_walkthrough.py` (the seal against a Python recompute of crew's form, `chapters.json`, the running progress read mid-take, the key rule, and a PASS+FAIL recording checked field by field).
+- **`_estate_client.py` keeps estate's diagnostics block (wicked-garden#1211).** The shim read `content[0]` of an MCP result only; estate's RetrievalTools put `STALENESS:` (and since estate#242 `CLAMPED:`, plus `LEXICAL-FALLBACK:`) in the second text block, so every skill going through the shim could not tell a stale or clamped answer from a fresh, complete one. `_unwrap_blocks(envelope)` returns `(payload, diagnostics_lines)`, `call_blocks(tool, arguments)` returns `{"result", "diagnostics"}`, and the CLI's `call` action — the command every skill names — prints `{"result": …, "diagnostics": [...]}` so the seat reading stdout sees the marker (additive: `result` is where it always was; a consumer that never reads `diagnostics` sees no change). `call`/`_unwrap` keep their one-value contract. The search skill and its hotspots ref say where the marker now appears. The governed read-verb allowlist the skill lint mirrors (`tests/test_skill_governed_grounding.py`) is unchanged: wicked-core's `ESTATE_READ_VERBS` still lacks `lineage`/`traverse`/`hotspots` (wicked-core#729 open), and garden must not coach a verb the fence denies.
+
+### Changed
+- **Domain vendor: the schema bundle `VERSION` follows the owner to 1.2.1.** wicked-core#699 bumped its governance schema bundle to 1.2.1 (conformance-rules 1.2.0 declares the DC-S1 project-rule fields it already documented). `skills/domain/vendor/VERSION` now matches, so `tests/domain/test_schema_vendor_pin.py` passes again against a current wicked-core checkout. `domain-model.schema.json` is byte-unchanged, and documents still carry `schema_version: "1.0.0"`.
+
+## [12.42.0] — 2026-10-03
+
+### Changed
+- **Demo recorder: encodes while it records; no frame file touches disk.** Before, `scripts/demo/stage.mjs` wrote every changed screencast frame as a JPEG (q95, 1920x1080: ~8 MB/s, about 5 GB per 10-minute take) and `postprocess.mjs` encoded them afterwards from an ffconcat list. Now a 30 fps ticker hands the newest screencast picture to an ffmpeg child over stdin (`-f image2pipe`), which writes the take's master `segments/<key>/capture.mp4` live: H.264 at a near-lossless CRF 12 with one-second fragments (`+frag_keyframe+empty_moov`), so a take that dies leaves a file that plays up to its last complete second. Master frame k is the picture at t0 + k/30, so wall clock → video time stays one line and `videoClock()` keeps its contract (`outAt`, the trim, the time-lapse spans). `buildVideo()` is now a cut of the master: `trim` for the opening, a `select` that keeps one frame in `factor` across every `Stage.fast()` span and re-times the rest back to back, the chapter markers, the final CRF 17 pass; no frame files are read. Each segment keeps `capture.mp4` + `timeline.json` (what `--reencode` re-cuts from) in place of `frames/`; a failed take's `failed-<take>/` keeps the master only when no video could be cut from it, as it kept the frames. The timeline is rewritten at every mark, so a recorder killed mid-take leaves a cuttable master and clock. A dead encoder fails the take at its next step (`encoder_failed`) instead of filming into nothing. `DEMO_KEEP_FRAMES=1` also dumps every screencast frame to `frames/` (with `timeline.json` `frames` timestamps) for debugging. Measured on one take against the 12.41.0 recipe run on the same frames: see `tests/demo/test_live_encode.py` (SSIM against the frames recipe and against a lossless build of the frames; the pipe's video is as close to the frames as the single-encode recipe was). `contact_sheet.py` already read the video. Timelines recorded by earlier versions (frames, no master) are not re-cut: re-record the segment.
+
 ## [12.41.0] — 2026-10-03
 
 ### Added
@@ -966,7 +980,9 @@ through `v9.2.18`. Major themes across that span:
 
 For each of those releases, see the corresponding tag in git history.
 
-[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...HEAD
+[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.43.0...HEAD
+[12.43.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.42.0...v12.43.0
+[12.42.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...v12.42.0
 [12.41.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.40.0...v12.41.0
 [12.40.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.39.0...v12.40.0
 [12.39.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.38.1...v12.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.41.0",
+  "version": "12.43.0",
   "type": "module",
   "description": "Curated toolkit for what AI coding agents can't do alone: evidence-gated work, codegraph relationships, deterministic multi-file refactor, multi-model second opinions, and cross-session memory. Installs as a Claude Code plugin.",
   "keywords": [

package/scripts/_estate_client.py

@@ -727,31 +727,51 @@ def _rpc(method: str, params: dict, *, timeout: float) -> Optional[dict]:
     return responses.get(2)
 
 
-def _unwrap(envelope: Optional[dict]) -> Optional[Any]:
-    """Extract a tool's payload from an MCP tools/call envelope.
-
-    Estate wraps results as {"result": {"content": [{"type":"text","text": …}],
-    "isError": bool}}. The text is usually the tool's own JSON string, which is
-    parsed and returned; a tool that emits plain (non-JSON) text gets its text
-    handed back verbatim as a str. Returns None on error / isError=true /
-    a malformed envelope shape.
+def _unwrap_blocks(envelope: Optional[dict]) -> "tuple[Optional[Any], list[str]]":
+    """Extract a tool's payload AND its diagnostics from an MCP tools/call envelope.
+
+    Estate wraps results as {"result": {"content": [{"type":"text","text": …}, …],
+    "isError": bool}}. `content[0]` is the tool's own JSON string, which is parsed
+    and returned (a tool that emits plain, non-JSON text gets its text handed back
+    verbatim as a str). `content[1]`, when present, is the diagnostics block the
+    estate MCP server appends (`wicked-estate-mcp/src/lib.rs`, "Append diagnostics
+    as a second text block"): one line each — `STALENESS: …` (W7.4 freshness),
+    `CLAMPED: …` (estate#242, a bound the server lowered), `LEXICAL-FALLBACK: …`.
+    They are returned as a list of lines so a caller can tell a stale or clamped
+    answer from a fresh, complete one (wicked-garden#1211).
+
+    Returns (None, []) on error / isError=true / a malformed envelope shape.
     """
     if not isinstance(envelope, dict):
-        return None
+        return None, []
     result = envelope.get("result")
     if not isinstance(result, dict) or result.get("isError"):
-        return None
+        return None, []
     content = result.get("content")
     if not isinstance(content, list) or not content:
-        return None
+        return None, []
     text = content[0].get("text") if isinstance(content[0], dict) else None
     if text is None:
-        return None
+        return None, []
     try:
-        return json.loads(text)
+        payload: Any = json.loads(text)
     except (json.JSONDecodeError, TypeError):
         # Some tools may return plain text; hand it back verbatim.
-        return text
+        payload = text
+    diagnostics: list[str] = []
+    for block in content[1:]:
+        more = block.get("text") if isinstance(block, dict) else None
+        if isinstance(more, str):
+            diagnostics.extend(line for line in more.split("\n") if line.strip())
+    return payload, diagnostics
+
+
+def _unwrap(envelope: Optional[dict]) -> Optional[Any]:
+    """The payload alone (`content[0]` parsed) — see `_unwrap_blocks` for both blocks.
+
+    Returns None on error / isError=true / a malformed envelope shape.
+    """
+    return _unwrap_blocks(envelope)[0]
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -791,6 +811,24 @@ def call(tool: str, arguments: Optional[dict] = None, timeout: float = 8.0) -> O
         return None
 
 
+def call_blocks(tool: str, arguments: Optional[dict] = None, timeout: float = 8.0) -> Optional[dict]:
+    """Like `call`, but keep the diagnostics block (wicked-garden#1211).
+
+    Returns {"result": <parsed payload>, "diagnostics": [<line>, …]} — the
+    `STALENESS:` / `CLAMPED:` / `LEXICAL-FALLBACK:` lines estate rides in the
+    second content block — or None when estate is unreachable or the tool
+    errored (the same fail-open shape as `call`).
+    """
+    try:
+        env = _rpc("tools/call", {"name": tool, "arguments": arguments or {}}, timeout=timeout)
+    except Exception:
+        return None
+    payload, diagnostics = _unwrap_blocks(env)
+    if payload is None and not diagnostics:
+        return None
+    return {"result": payload, "diagnostics": diagnostics}
+
+
 def call_raw(tool: str, arguments: Optional[dict] = None, timeout: float = 8.0) -> Optional[dict]:
     """Like `call`, but return the full MCP envelope (for callers that need
     `isError` / staleness diagnostics). Fail-open (None)."""
@@ -1053,7 +1091,11 @@ def main(argv: list) -> int:
         if not tool:
             _emit({"error": "call requires {\"tool\": \"<ToolName>\", \"arguments\": {...}}"})
             return 1
-        _emit({"result": call(tool, args.get("arguments", {}))})
+        # Both blocks, in-band (wicked-garden#1211): the seat reading stdout sees the
+        # `STALENESS:` / `CLAMPED:` lines beside the payload, as the MCP caller does.
+        blocks = call_blocks(tool, args.get("arguments", {}))
+        _emit({"result": blocks["result"] if blocks else None,
+               "diagnostics": blocks["diagnostics"] if blocks else []})
     elif action == "propose":
         kind_type = args.get("kind_type")
         payload = args.get("payload")

package/scripts/demo/postprocess.mjs

@@ -1,60 +1,91 @@
-// Part of the wicked-garden-demo skill. Turns a recorded timeline (frames + marks) into a 1080p H.264 MP4 with chapter markers.
+// Part of the wicked-garden-demo skill. Cuts a take's master (capture.mp4 + timeline.json) into a 1080p H.264 MP4
+// with chapter markers.
 //
-// Each screencast frame lasts until the next one; spans marked by Stage.fast() are compressed by their factor,
-// so long model waits play as a visible time-lapse while the on-screen badge states the real elapsed time.
+// The master is the take at a constant FPS, encoded live while it recorded (stage.mjs): frame k is the picture at
+// t0 + k/FPS, so wall clock and master time are the same line. The cut drops the opening trim, keeps one frame in
+// `factor` across every span marked by Stage.fast() and re-times what is left back to back, so long model waits play
+// as a visible time-lapse while the on-screen badge states the real elapsed time; the chapter marks land where
+// videoClock().outAt() says. No frame file is read or written.
 // Usage: wicked-garden run scripts/demo/postprocess.mjs <outDir> [output.mp4]
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
-const FPS = 30;
+/** The master's constant frame rate. */
+export const FPS = 30;
+/** The master's file name inside a take's directory. */
+export const CAPTURE = "capture.mp4";
+/** ffprobe beside a given ffmpeg binary (`FFMPEG=/path/to/ffmpeg` is honoured for both). */
+export const ffprobeOf = (ffmpeg) => ffmpeg.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1");
 
 /**
- * The video clock of a timeline: the frames buildVideo keeps, the time-lapse spans, and `outAt(t)`, the
- * position in the built video (seconds) of a wall-clock instant `t`. Throws when no frame is kept.
+ * The video clock of a timeline, in master frames so it agrees with the cut to the frame: `inFrame`, the first
+ * master frame kept; `spans`, the time-lapse spans as [a, b) frame ranges with their factor; `keptBefore(k)`, how many
+ * cut frames precede master frame k; and `outAt(t)`, the position in the cut video (seconds) of a wall-clock instant.
+ * Throws when a closed take says nothing was recorded past the trim; a timeline a killed take left (no frame count)
+ * is clocked from its t0 and the master is counted by buildVideo.
  */
 export function videoClock(tl, trimStart = 0) {
-  const frames = tl.frames.filter((f) => f.t >= tl.t0 + trimStart);
-  if (!frames.length) throw new Error("no frames recorded");
-  const speed = [...tl.marks.speed].sort((a, b) => a.start - b.start);
-
-  // Output time for a wall-clock instant: integrate 1/factor over the marked spans.
-  const origin = frames[0].t;
-  const outAt = (t) => {
-    let out = t - origin;
-    for (const s of speed) {
-      const a = Math.max(s.start, origin), b = Math.min(s.end, t);
-      if (b > a) out -= (b - a) * (1 - 1 / s.factor);
+  const fps = tl.capture?.fps ?? FPS;
+  const inFrame = Math.max(0, Math.ceil(trimStart * fps - 1e-9));
+  if (typeof tl.capture?.frames === "number" && tl.capture.frames <= inFrame) throw new Error("no frames recorded");
+  const toFrame = (t) => Math.round((t - tl.t0) * fps);
+  // Inside a span only frame a and every frame where floor((k - a) / factor) advances are kept: one in `factor`.
+  // Spans never overlap here: a later span starts where the one before it ends (a nested Stage.fast() counts once).
+  const spans = [];
+  for (const s of [...tl.marks.speed].sort((x, y) => x.start - y.start)) {
+    const a = Math.max(inFrame, toFrame(s.start), spans.length ? spans[spans.length - 1].b : 0), b = toFrame(s.end);
+    if (b > a && s.factor > 1) spans.push({ a, b, f: s.factor });
+  }
+  const keptIn = (a, b, f) => (b > a ? Math.floor((b - a - 1) / f) + 1 : 0);
+  const keptBefore = (k) => {
+    let kept = Math.max(0, k - inFrame);
+    for (const s of spans) {
+      const b = Math.min(s.b, k);
+      if (b > s.a) kept -= (b - s.a) - keptIn(s.a, b, s.f);
     }
-    return out;
+    return kept;
   };
-  return { frames, speed, outAt };
+  const outAt = (t) => keptBefore(toFrame(t)) / fps;
+  return { inFrame, fps, spans, keptIn, keptBefore, outAt, speed: tl.marks.speed };
+}
+
+/** Frames in the master, by demuxing it (exact for a master whose writer died: the complete packets count). */
+function countFrames(ffprobe, file) {
+  const r = spawnSync(ffprobe, ["-v", "error", "-select_streams", "v:0", "-count_packets", "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", file],
+    { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${(r.error?.message ?? r.stderr ?? "").slice(-500)}`);
+  const n = Number(r.stdout.trim());
+  if (!Number.isInteger(n)) throw new Error(`ffprobe gave no frame count for ${file}: ${r.stdout.slice(0, 200)}`);
+  return n;
 }
 
 export function buildVideo(outDir, outFile, { ffmpeg = process.env.FFMPEG || "ffmpeg", tail = 0.2, trimStart = 0 } = {}) {
   const tl = JSON.parse(fs.readFileSync(path.join(outDir, "timeline.json"), "utf8"));
-  const { frames, speed, outAt } = videoClock(tl, trimStart);
-
-  // Resample to constant frame rate: output tick k shows the newest frame captured at or before k/FPS, and each
-  // run of identical picks becomes one concat entry lasting (run length / FPS). Bursts collapse, gaps hold.
-  const outTimes = frames.map((f) => outAt(f.t));
-  // The screencast only emits a frame when the picture changes, so a static hold at the end (a closing card, a final
-  // pause) has no frame of its own: end at the moment recording stopped, not at the last captured frame.
-  const total = Math.max(outTimes[outTimes.length - 1] + 1 / FPS, outAt(tl.tEnd ?? frames[frames.length - 1].t)) + tail;
-  const ticks = Math.ceil(total * FPS);
-  const runs = [];
-  for (let k = 0, i = 0; k < ticks; k++) {
-    while (i + 1 < frames.length && outTimes[i + 1] <= k / FPS) i++;
-    if (runs.length && runs[runs.length - 1].i === i) runs[runs.length - 1].n++;
-    else runs.push({ i, n: 1 });
+  const capture = path.join(outDir, tl.capture?.file ?? CAPTURE);
+  if (!fs.existsSync(capture)) {
+    throw new Error(tl.capture?.error ?? `${path.basename(capture)} not found in ${outDir}` +
+      (Array.isArray(tl.frames) && !tl.capture ? " (recorded from frames by an earlier version; re-record the segment)" : ""));
   }
-  const lines = ["ffconcat version 1.0"];
-  for (const r of runs) lines.push(`file 'frames/${frames[r.i].file}'`, `duration ${(r.n / FPS).toFixed(6)}`);
-  lines.push(`file 'frames/${frames[runs[runs.length - 1].i].file}'`); // concat demuxer needs the last file repeated
-  fs.writeFileSync(path.join(outDir, "frames.ffconcat"), lines.join("\n"));
+  const { inFrame, fps, spans, keptBefore, outAt, speed } = videoClock(tl, trimStart);
+  // What the master holds is what counts: an encoder that died late still left playable fragments to cut, and its
+  // failure is the explanation only when nothing can be.
+  let nFrames;
+  try { nFrames = countFrames(ffprobeOf(ffmpeg), capture); } catch (e) { throw new Error(tl.capture?.error ?? e.message); }
+  if (nFrames <= inFrame) throw new Error(tl.capture?.error ?? "no frames recorded");
+
+  // Master frame k is the picture at t0 + k/fps. Inside a marked span one frame in `factor` is kept; the kept frames
+  // are re-timed back to back at fps. In the select expression n counts frames after the trim (n = k - inFrame).
+  const keep = spans.filter((s) => s.a < nFrames).reduce((rest, s) => {
+    const a = s.a - inFrame, b = Math.min(s.b, nFrames) - inFrame - 1;
+    return `if(between(n\\,${a}\\,${b})\\,gt(floor((n-${a})/${s.f})\\,floor((n-${a}-1)/${s.f}))\\,${rest})`;
+  }, "1");
+  const kept = keptBefore(nFrames);
+  const total = kept / fps + tail;
 
-  const chapters = tl.marks.chapters.map((c) => ({ ...c, out: Math.max(0, outAt(c.t)) }));
+  // A chapter marked after the master's last frame (a take killed within the second) sits at the end, not past it.
+  const chapters = tl.marks.chapters.map((c) => ({ ...c, out: Math.min(Math.max(0, outAt(c.t)), kept / fps) }));
   const meta = [";FFMETADATA1", `title=${(tl.title || "Demo").replace(/[=;#\\\n]/g, " ")}`];
   chapters.forEach((c, i) => {
     const start = Math.round(c.out * 1000), end = Math.round((i + 1 < chapters.length ? chapters[i + 1].out : total) * 1000);
@@ -62,15 +93,18 @@ export function buildVideo(outDir, outFile, { ffmpeg = process.env.FFMPEG || "ff
   });
   fs.writeFileSync(path.join(outDir, "chapters.ffmeta"), meta.join("\n") + "\n");
 
-  const args = ["-y", "-f", "concat", "-safe", "0", "-i", "frames.ffconcat", "-i", "chapters.ffmeta", "-map_metadata", "1", "-map_chapters", "1",
-    "-t", total.toFixed(3), "-vf", `fps=${FPS},format=yuv420p`, "-c:v", "libx264", "-preset", "slow", "-crf", "17", "-tune", "stillimage", "-movflags", "+faststart", path.resolve(outFile)];
+  // tpad holds the last picture for `tail` (a static close has frames of its own in the master, but the cut
+  // should not end on the very tick recording stopped).
+  const vf = `trim=start_frame=${inFrame},select='${keep}',setpts=N/(${fps}*TB),tpad=stop_mode=clone:stop_duration=${tail.toFixed(3)},format=yuv420p`;
+  const args = ["-y", "-i", capture, "-i", "chapters.ffmeta", "-map_metadata", "1", "-map_chapters", "1", "-vf", vf, "-r", String(fps), "-fps_mode", "cfr",
+    "-c:v", "libx264", "-preset", "slow", "-crf", "17", "-tune", "stillimage", "-movflags", "+faststart", path.resolve(outFile)];
   const r = spawnSync(ffmpeg, args, { cwd: outDir, stdio: ["ignore", "ignore", "pipe"] });
-  if (r.status !== 0) throw new Error(`ffmpeg failed: ${r.stderr?.toString().slice(-2000)}`);
+  if (r.status !== 0) throw new Error(`ffmpeg failed: ${(r.error?.message ?? r.stderr?.toString() ?? "").slice(-2000)}`);
 
   const fmt = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
   const md = ["| Time | Chapter |", "|---|---|", ...chapters.map((c) => `| ${fmt(c.out)} | ${c.title} |`)];
   fs.writeFileSync(path.join(outDir, "chapters.md"), md.join("\n") + "\n");
-  return { seconds: total, chapters: chapters.map((c) => ({ at: fmt(c.out), title: c.title })), speedups: speed.length, frames: frames.length };
+  return { seconds: total, chapters: chapters.map((c) => ({ at: fmt(c.out), title: c.title })), speedups: speed.length, frames: nFrames - inFrame };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {

package/scripts/demo/record.mjs

@@ -10,14 +10,15 @@
 // segments/<key>/failed-<take>/ and is never stitched.
 //
 // Each non-intro segment opens on its own chapter slide (the storyline's beforeSegment hook runs behind it) and ends
-// on the plain stage background, so segments join with a clean cut. Frames and timelines are kept per segment, so a
-// segment can be re-recorded alone and the whole video re-encoded without recording again.
+// on the plain stage background, so segments join with a clean cut. Each segment keeps its master (capture.mp4,
+// encoded live while it recorded) and timeline.json, so a segment can be re-recorded alone and the whole video
+// re-cut (--reencode) without recording again. No frame files are written (DEMO_KEEP_FRAMES=1 dumps them for debugging).
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { Stage } from "./stage.mjs";
-import { buildVideo, videoClock } from "./postprocess.mjs";
+import { buildVideo, videoClock, CAPTURE, ffprobeOf } from "./postprocess.mjs";
 import { fixtureOrigin, sideEffectError } from "./readonly.mjs";
 
 // ---- module-level constants (used by exports) --------------------------------------------------
@@ -78,6 +79,49 @@ export function failedAtInVideo(dir, failedAt, trimStart = SEGMENT_TRIM_START) {
   }
 }
 
+// ---- exported stitch ---------------------------------------------------------------------------
+/**
+ * Join segment videos (same codec, size and frame rate — every take is cut by buildVideo) into one MP4 with
+ * chapter metadata, without re-encoding. `parts` = [{ title, file }] in take order; `workDir` holds the two
+ * ffmpeg list files. Returns the `| m:ss | Title |` marker rows (chapters.md) and the total seconds.
+ */
+export function stitchParts(parts, outFile, { ffmpeg = "ffmpeg", title = "Demo", workDir }) {
+  const ffprobe = ffprobeOf(ffmpeg);
+  const probeSeconds = (file) => {
+    const r = spawnSync(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file], { encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${r.stderr}`);
+    return Number(r.stdout.trim());
+  };
+  if (!parts.length) throw new Error("no segments recorded yet");
+  fs.mkdirSync(workDir, { recursive: true });
+  const list = path.join(workDir, "concat.txt");
+  fs.writeFileSync(list, parts.map((p) => `file '${p.file.replace(/\\/g, "/").replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+  let at = 0;
+  const meta = [";FFMETADATA1", `title=${String(title).replace(/[=;#\\\n]/g, " ")}`];
+  const rows = ["| Time | Chapter |", "|---|---|"];
+  for (const p of parts) {
+    const d = probeSeconds(p.file);
+    meta.push("[CHAPTER]", "TIMEBASE=1/1000", `START=${Math.round(at * 1000)}`, `END=${Math.round((at + d) * 1000)}`, `title=${String(p.title).replace(/[=;#\\\n]/g, " ")}`);
+    rows.push(`| ${Math.floor(at / 60)}:${String(Math.floor(at % 60)).padStart(2, "0")} | ${p.title} |`);
+    at += d;
+  }
+  const metaFile = path.join(workDir, "chapters.ffmeta");
+  fs.writeFileSync(metaFile, meta.join("\n") + "\n");
+  const r = spawnSync(ffmpeg, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-i", metaFile, "-map", "0", "-map_metadata", "1",
+    "-map_chapters", "1", "-map", "-0:d", "-c", "copy", "-movflags", "+faststart", outFile], { stdio: ["ignore", "ignore", "pipe"] });
+  if (r.status !== 0) throw new Error(`stitch failed: ${r.stderr?.toString().slice(-1500)}`);
+  return { seconds: at, rows };
+}
+
+/** One frame of a video as a JPEG (`atSec` into it); false when ffmpeg could not decode one there. */
+export function extractFrame(video, atSec, outFile, { ffmpeg = "ffmpeg" } = {}) {
+  const r = spawnSync(ffmpeg, ["-y", "-ss", String(Math.max(0, atSec)), "-i", video, "-frames:v", "1", "-q:v", "3", outFile],
+    { stdio: ["ignore", "ignore", "pipe"] });
+  const ok = r.status === 0 && fs.existsSync(outFile) && fs.statSync(outFile).size > 0;
+  if (!ok) fs.rmSync(outFile, { force: true });
+  return ok;
+}
+
 // ---- exported recorder factory -----------------------------------------------------------------
 /**
  * Build a reusable per-segment recorder bound to a story context.
@@ -125,12 +169,15 @@ export function makeSegmentRecorder({
     let videoError = null;
     if (fs.existsSync(tlPath)) {
       fs.renameSync(tlPath, path.join(dir, "timeline.json"));
-      if (fs.existsSync(path.join(localSegDir(key), "frames"))) fs.renameSync(path.join(localSegDir(key), "frames"), path.join(dir, "frames"));
+      // The master (and the frames dump, if any) go with the timeline; they are dropped once a video is built from them.
+      for (const f of [CAPTURE, "frames"]) {
+        if (fs.existsSync(path.join(localSegDir(key), f))) fs.renameSync(path.join(localSegDir(key), f), path.join(dir, f));
+      }
       try {
         buildVideo(dir, path.join(dir, "segment.mp4"), { trimStart, ffmpeg: FFMPEG_BIN });
         video = "segment.mp4";
+        fs.rmSync(path.join(dir, CAPTURE), { force: true });
         fs.rmSync(path.join(dir, "frames"), { recursive: true, force: true });
-        fs.rmSync(path.join(dir, "frames.ffconcat"), { force: true });
       } catch (e) {
         videoError = e.message;
         fs.rmSync(path.join(dir, "segment.mp4"), { force: true });
@@ -159,14 +206,15 @@ export function makeSegmentRecorder({
     console.log(`● ${seg.key} (take ${take})`);
     const stage = new Stage({
       baseUrl, outDir: localSegDir(seg.key), chapters: CHAPTERS_LIST, brand,
-      stickyOffset: story.stickyOffset, headful: process.env.DEMO_HEADFUL === "1",
-      locale: story.locale, timezoneId: story.timezoneId, writableOrigin, consoleHandler,
+      stickyOffset: story.stickyOffset, headful: process.env.DEMO_HEADFUL === "1", keepFrames: process.env.DEMO_KEEP_FRAMES === "1",
+      locale: story.locale, timezoneId: story.timezoneId, writableOrigin, consoleHandler, ffmpeg: FFMPEG_BIN,
     });
     const timings = {};
     let ctx = makeCtx(stage, timings);
     fs.mkdirSync(localSegDir(seg.key), { recursive: true });
     fs.rmSync(localSegVideo(seg.key), { force: true });
     fs.rmSync(path.join(localSegDir(seg.key), "timeline.json"), { force: true });
+    fs.rmSync(path.join(localSegDir(seg.key), CAPTURE), { force: true });
     let failure = null;
     let failedAt = null;
     try {
@@ -203,7 +251,8 @@ export function makeSegmentRecorder({
     } finally {
       await stage.close().catch(() => {});
     }
-    let err = failure;
+    // An encoder that failed while close() drained it is a failed take too: its master may be short of the end.
+    let err = failure ?? stage.encoderError ?? null;
     if (stage.blocked.length) {
       err = sideEffectError(seg.key, stage.blocked);
       if (failure !== null) err.cause = failure;
@@ -235,7 +284,6 @@ export function makeSegmentRecorder({
 // ---- CLI entry point (only runs when invoked directly) -----------------------------------------
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const FFMPEG = process.env.FFMPEG || "ffmpeg";
-  const FFPROBE = FFMPEG.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1");
 
   function usage(msg) {
     if (msg) console.error(`error: ${msg}\n`);
@@ -296,12 +344,6 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   const readTimings = (key) => { try { return JSON.parse(fs.readFileSync(path.join(segDir(key), "timings.json"), "utf8")); } catch { return {}; } };
 
   // ---- stitch ----
-  function probeSeconds(file) {
-    const r = spawnSync(FFPROBE, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file], { encoding: "utf8" });
-    if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${r.stderr}`);
-    return Number(r.stdout.trim());
-  }
-
   /** A segment's guard.json (how its last take was recorded), or null when it has none. */
   function readGuard(key) {
     try { return JSON.parse(fs.readFileSync(path.join(segDir(key), "guard.json"), "utf8")); } catch { return null; }
@@ -327,24 +369,10 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     refuseFailedTakes();
     const segs = SEGMENTS.filter((s) => fs.existsSync(segVideo(s.key)));
     const missing = SEGMENTS.filter((s) => !fs.existsSync(segVideo(s.key))).map((s) => s.key);
-    if (!segs.length) throw new Error("no segments recorded yet");
-    const list = path.join(SEG_DIR, "concat.txt");
-    fs.writeFileSync(list, segs.map((s) => `file '${segVideo(s.key).replace(/\\/g, "/").replace(/'/g, "'\\''")}'`).join("\n") + "\n");
-    let at = 0;
-    const meta = [";FFMETADATA1", `title=${(story.title || "Demo").replace(/[=;#\\\n]/g, " ")}`];
-    const rows = ["| Time | Chapter |", "|---|---|"];
-    for (const s of segs) {
-      const d = probeSeconds(segVideo(s.key));
-      const title = s.intro ? "Introduction" : s.title;
-      meta.push("[CHAPTER]", "TIMEBASE=1/1000", `START=${Math.round(at * 1000)}`, `END=${Math.round((at + d) * 1000)}`, `title=${title.replace(/[=;#\\\n]/g, " ")}`);
-      rows.push(`| ${Math.floor(at / 60)}:${String(Math.floor(at % 60)).padStart(2, "0")} | ${title} |`);
-      at += d;
-    }
-    fs.writeFileSync(path.join(SEG_DIR, "chapters.ffmeta"), meta.join("\n") + "\n");
-    // Segments share codec, size and frame rate, so they join without re-encoding.
-    const r = spawnSync(FFMPEG, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-i", path.join(SEG_DIR, "chapters.ffmeta"), "-map", "0", "-map_metadata", "1",
-      "-map_chapters", "1", "-map", "-0:d", "-c", "copy", "-movflags", "+faststart", FINAL], { stdio: ["ignore", "ignore", "pipe"] });
-    if (r.status !== 0) throw new Error(`stitch failed: ${r.stderr?.toString().slice(-1500)}`);
+    const { seconds: at, rows } = stitchParts(
+      segs.map((s) => ({ title: s.intro ? "Introduction" : s.title, file: segVideo(s.key) })),
+      FINAL, { ffmpeg: FFMPEG, title: story.title || "Demo", workDir: SEG_DIR },
+    );
     fs.writeFileSync(path.join(OUT, "chapters.md"), rows.join("\n") + "\n");
     fs.writeFileSync(path.join(OUT, "timings.json"), JSON.stringify(Object.fromEntries(SEGMENTS.map((s) => [s.key, readTimings(s.key)])), null, 2));
     // How the stitched segments were recorded: read-only only when every one of them was (a segment recorded