lastlight 0.16.0 → 0.16.1

package/skills/code-review/SKILL.md

@@ -1,82 +0,0 @@
----
-name: code-review
-description: The shared rubric for reviewing a code change — precision-first, high-signal findings only (Critical/Important), plus what to check (correctness, security, edge cases, regression risk, test coverage). Use when reviewing a PR or a branch diff.
-version: 2.0.0
-tags: [review, code-quality]
----
-
-# Code Review
-
-The shared rubric for assessing a code change. Used both by a PR review and by
-the build cycle's branch-diff reviewer — the *procedure* differs (where the diff
-comes from, how the verdict is recorded), but the rubric below is the same.
-
-Review the change **in full context** — read each changed file, not just the
-hunk. For a large change (>300 lines or >5 files): trace data flow through
-modified functions, check callers of anything whose signature or behaviour
-changed for regression risk, and check that tests cover the actual risk areas,
-not just the happy path.
-
-## Precision first — post only what matters
-
-A review is only useful if people trust it. A noisy reviewer gets muted; every
-low-value comment you post spends the credibility of the ones that matter. So
-the bar is **high-signal only**:
-
-- **Post only Critical and Important findings.** Suggestions and Nits (below)
-  are *not* worth a formal review comment on their own — drop them, or fold at
-  most one genuinely valuable line into the summary. When in doubt, leave it out.
-- **If you cannot name the concrete impact — what breaks, and for which input or
-  caller — do not post it.** "This could be cleaner" is not a finding; "this
-  crashes when `items` is empty because line 42 indexes `[0]`" is.
-- **Confidence gate.** Before you finalise, re-read each finding against the
-  actual code and try to *refute your own claim*. If you can't defend it against
-  what the code actually does (not what you assumed), drop it. A missed marginal
-  issue costs far less than a wrong one.
-
-## Finding tiers
-
-Categorise every finding into exactly one tier. **Only Critical and Important
-are posted** (see Precision first):
-
-- **Critical** — security issues, data loss, breaking changes, silent
-  data-dropping (see Correctness below). Blocks merge.
-- **Important** — missing tests, performance problems, type errors, **avoidable
-  duplication**, **excessive complexity**, **compiler-silencing assertions**.
-  Should fix.
-- **Suggestions** — clarity, naming, minor DRY tidy-ups. *Not posted* — noise
-  in a formal review.
-- **Nits** — style, formatting. *Not posted* — this is the linter's job.
-
-Every posted finding carries a **one-line concrete impact**: the consequence
-(what breaks / for whom) and, where it helps, the fix. That local reasoning is
-what makes a comment actionable rather than a vague worry.
-
-## What to check
-
-- **Correctness** — does it do what it claims? Logic errors, off-by-one, wrong
-  conditions, mishandled async. **A silent default or a dropped output for an
-  input the code doesn't support is a correctness bug, not graceful handling** —
-  flag any unsupported case that is silently defaulted, skipped, or omitted
-  instead of warned-and-skipped or warned-and-surfaced.
-- **Edge cases** — empty/null inputs, boundaries, error paths, concurrency.
-- **Security** — injection, auth/authorization, secret handling, untrusted input.
-- **Complexity** — flag functions past ~15 cyclomatic complexity or that mix
-  parse/validate/emit responsibilities; ask for helper extraction. This is an
-  **Important** finding, not a nit.
-- **Duplication** — flag avoidable duplicated logic (two or more clone groups of
-  the same code/branching). DRY is **should-fix** here, not merely "nice to have."
-- **Type safety** — flag `as any`, unchecked `as`-casts, or `@ts-ignore` used to
-  silence the compiler or to bypass a validator the same code path defines.
-- **Regression risk** — existing callers of changed functions; behaviour changes
-  that ripple.
-- **Test coverage** — do the tests exercise the real risk, or just the happy path?
-- **Fit** — does it match the codebase's existing patterns and conventions?
-
-## Calibration
-
-- Don't nitpick generated files (lockfiles, compiled assets).
-- Don't repeat what linters/CI already catch.
-- Don't block over style preferences alone.
-- Read the room: if a human reviewer already approved, lower the bar for blocking
-  — prefer a comment over requesting changes on non-critical findings.

package/skills/debug-production/SKILL.md

@@ -1,108 +0,0 @@
----
-name: debug-production
-description: Debug a running Last Light instance (usually production) via the `lastlight` CLI instead of SSH. Use when investigating a failed/stuck workflow, a bad agent run, a phase error, or "why didn't the bot do X" — anything that previously meant SSHing in to read SQLite or session logs.
-version: 1.0.0
-tags: [ops, debugging, cli]
----
-
-# Debug a Last Light instance via the CLI
-
-Read a running instance's state over its admin API with the `lastlight` CLI —
-no SSH, no poking SQLite or jsonl files on the box. Every command takes
-`--json` for machine-parseable output; prefer it when you need to extract
-fields.
-
-## 0. Connect
-
-The CLI talks to whatever instance you logged into (saved in
-`~/.lastlight/config.json`). Confirm you're pointed at the right one and the
-token is valid:
-
-```bash
-lastlight status            # instance URL, server health, token validity
-```
-
-If the token is missing/expired, authenticate (the prod instance URL lives in
-local agent memory — see the "Last Light production server" note):
-
-```bash
-lastlight login https://<instance>     # browser handoff (password/Slack/GitHub)
-lastlight login https://<instance> --password   # headless fallback
-```
-
-For one-off targeting without saving, pass `--url` / `--token` on any command,
-or set `LASTLIGHT_URL` / `LASTLIGHT_TOKEN` (env wins over the saved config).
-
-## 1. Find the broken run
-
-```bash
-lastlight workflow list --status failed          # recent failures
-lastlight workflow list --status active          # running + paused now
-lastlight workflow list --workflow pr-review --limit 50
-```
-
-Copy the run `ID` from the table.
-
-## 2. Inspect the run's phases
-
-```bash
-lastlight workflow log <run-id>          # run header + per-phase table (✓/✗, duration, session id, error)
-lastlight workflow log <run-id> --follow # then tail the current phase live
-```
-
-The phase table shows which phase failed, its error snippet, and the `SESSION`
-id you need for the transcript.
-
-## 3. Read / tail the agent transcript
-
-```bash
-lastlight session list                   # recent sandbox sessions (TYPE, MODEL, LIVE)
-lastlight session log <session-id>       # full transcript
-lastlight session log <session-id> --follow   # live tail (SSE) of an in-flight phase
-```
-
-## 4. Search across runs
-
-```bash
-lastlight logs search "ECONNREFUSED"                 # errors ledger (default)
-lastlight logs search "rate limit" --scope all       # errors + transcript content
-lastlight logs search "could not clone" --scope messages --limit 20
-```
-
-`--scope errors` (default) matches the executions ledger (error/skill/repo);
-`messages` greps recent session transcripts; `all` does both.
-
-## 5. Raw server / docker logs
-
-When the workflow + session views aren't enough — a crash before any session
-was written, a sidecar misbehaving, harness boot errors — read the actual
-container logs (`docker logs`) over the API:
-
-```bash
-lastlight server list                    # the lastlight-* containers + status
-lastlight server logs                    # the agent harness (default), last 200 lines
-lastlight server logs --tail 500 --since 10m
-lastlight server logs --follow           # live tail (Ctrl-C to stop)
-lastlight server logs coredns-strict     # a specific sidecar by service or container name
-```
-
-## 6. Approvals & health
-
-```bash
-lastlight approvals list                 # paused gates waiting on a human
-lastlight approvals approve <id> --reason "looks good"
-lastlight approvals reject  <id> --reason "wrong approach"
-
-lastlight stats                          # totals + per-skill success/fail
-lastlight stats --daily 14               # last 14 days of cost/tokens
-```
-
-## Tips
-
-- Add `--json` to any command to pipe into `jq` (e.g.
-  `lastlight workflow list --status failed --json | jq -r '.workflowRuns[].id'`).
-- Triage flow: `workflow list --status failed` → `workflow log <id>` → grab the
-  failed phase's session → `session log <session-id>` → if it's a recurring
-  symptom, `logs search "<error text>"` to see how often it happens.
-- These are read-only except `approvals approve/reject` and the trigger
-  commands (`build`/`triage`/`review`/…) — debugging never mutates the box.

package/skills/demo/SKILL.md

@@ -1,228 +0,0 @@
----
-name: demo
-description: Record a short demo VIDEO of a PR or feature — drive the repo's web UI in a real headless browser, capture the session, and composite a titled, size-capped mp4 with ffmpeg. Use on the docker QA image when the deliverable is a playable demo clip (single walkthrough or before/after comparison), not a text/screenshot report.
-version: 1.0.0
-tags: [demo, video, browser, ffmpeg, evidence]
----
-
-# Demo
-
-Turn a PR or feature into a short, polished **demo video**: drive the repo's
-web UI in a real headless Chromium, screen-record the session, and composite a
-titled, size-capped **mp4** the maintainer can watch inline.
-
-This is the **video** sibling of `browser-qa` (screenshots) and `verify`/
-`qa-test` (text evidence). It only works on the `lastlight-sandbox-qa:latest`
-docker image, which bakes in Playwright + Chromium **and ffmpeg**. You have
-bash + file tools but **no vision** — you reason over the driver's JSON stdout
-and the ffprobe summary; you never "see" the video.
-
-Compositing is **ffmpeg only** — there is no Remotion / cinematic-effects
-pipeline. You get a title card, optional before/after side-by-side, trim/speed,
-and a size cap. That's the deliverable: a clear, honest walkthrough, not a
-marketing reel.
-
-This skill uses **browser-qa** (the headless driver) and **building** (install
-+ start the dev-server).
-
-## When this applies
-
-A phase on the docker QA image whose target is a **web app** the repo serves on
-`localhost`, where a *moving* demonstration adds value over a screenshot. For a
-CLI, a curl-able API, or pure pass/fail evidence, use `qa-test`/`verify`. For
-static screenshot evidence, use `browser-qa`. Don't record a video you don't
-need.
-
-## FIRST — probe for a browser
-
-The browser driver lives in the **browser-qa** skill bundle at
-`<browser-qa-dir>/scripts/agent-browser.mjs`, and this skill's compositor at
-`<demo-dir>/scripts/compose-demo.sh`. Resolve both `<…-dir>` paths from the
-available-skills catalogue (it gives each skill's absolute staged path); do not
-assume a relative path from `$PWD` — your cwd is the checked-out repo, the
-bundles are siblings.
-
-Run the runtime probe before anything else:
-
-```bash
-node <browser-qa-dir>/scripts/agent-browser.mjs doctor
-```
-
-- Exit 0 with `{"ok":true,...}` → proceed.
-- Exit non-zero (lean image / gondolin / no Chromium) → **DO NOT attempt a demo.**
-  Report that the demo path was unavailable on this host and stop. (The workflow
-  gates this phase to the QA image, so this should be rare — but never fake a
-  recording.)
-
-## Understand what to prove
-
-Read the PR (description, diff, linked issue) from the context the prompt gives
-you. For each change, ask: *what could a viewer confuse this with?* Design the
-demo so the viewer sees something that **only happens if the feature works as
-claimed** — both states (before/after, input/result) must appear on screen.
-
-State your **commitments** up front, then honour them:
-
-- **Layout** — `single` (default: a new feature, a fix proof, a walkthrough) or
-  `side-by-side` (only when the story is fundamentally a comparison: regression
-  fixed, behaviour-preserving refactor). Never fabricate a "before" to justify
-  side-by-side.
-- **Speed** — target a watchable length; speed up dead time rather than leaving
-  it. 30–60s is a good single-feature target.
-
-## Build and run the app
-
-Follow the **building** skill to install dependencies, then start the repo's
-dev-server **in the background** and poll with `curl` until it answers on
-`localhost:PORT`. Note the port — you pass it as `--base-url`.
-
-## Capture the session
-
-Author a `flow.json` (same shape as **browser-qa**) that scripts the
-interaction as a *director*, not an operator:
-
-- **Record the baseline first** — the starting state is act one.
-- **Hold after state changes** — add a `{"pause": 1200}` (or `waitFor`) so the
-  result is readable before moving on.
-- **Verify between steps** — `waitFor` the expected element before the next
-  action; don't blindly fire keys into an unsettled page.
-
-Because recording auto-enables the driver's **demo mode**, you get a visible
-**synthetic cursor** that animates to each target, and holds between steps —
-you don't script those. To make typing visible on screen, prefer **`type`**
-(character-by-character) over `fill` (instant) for any input the viewer should
-watch being filled. Tune pacing with `--step-delay` / `--type-delay` if a flow
-feels rushed or draggy (see the browser-qa skill).
-
-Record the session by passing `--record-dir`:
-
-```bash
-node <browser-qa-dir>/scripts/agent-browser.mjs run flow.json \
-  --base-url http://localhost:PORT \
-  --record-dir /tmp/demo-cap
-# → writes /tmp/demo-cap/session.webm, reports {"video":"…/session.webm", …}
-```
-
-Pick the viewport to match the layout so the clip isn't letterboxed (the
-compositor renders at **1920×1080** by default): `1920x1080` for `single`;
-`~960x1000` per panel for `side-by-side` (set it in the flow's `viewport`).
-Recording at the output resolution keeps UI text crisp instead of upscaled.
-
-**Before/after comparison:** record the **same** scripted interaction against
-each branch — `session-after.webm` (PR head) and `session-before.webm` (base
-branch). Only the behaviour should differ.
-
-When the harness triggered this on a PR, your workspace is **already checked out
-at the PR head** — record the *after* from that current checkout first (no
-re-checkout). Then get the *before* from the base branch. The pre-clone is
-shallow + single-branch, so fetch the base **by ref** (the prompt passes its
-name) rather than trusting a local branch name, which may be a synthesized
-`lastlight/N-slug` that actually points at the default branch:
-
-```bash
-git fetch --depth 1 origin <baseBranch>
-git checkout -B <baseBranch>-base FETCH_HEAD   # re-install deps + restart the dev-server after switching
-```
-
-**Verify the checkout did what you think before you composite:** read the
-disambiguating element on *both* recordings (the driver's `text`/`assertText`).
-It MUST be present in *after* and absent in *before*. If both look identical, the
-checkout is wrong (a stale/fictional branch, deps not rebuilt, or a dev-server
-still serving the old branch) — STOP and fix it. Never ship a side-by-side that
-shows no difference and call it a before/after; that is the failure this skill
-exists to prevent.
-
-## Compose the video
-
-Composite the raw recording(s) into the final mp4 with the bundled wrapper:
-
-```bash
-# Single walkthrough
-<demo-dir>/scripts/compose-demo.sh \
-  --output <artifact-dir>/demo.mp4 \
-  --title "PR #42 — Add dark mode toggle" \
-  --subtitle "Toggling persists the theme across reloads" \
-  --layout single --speed 1 \
-  /tmp/demo-cap/session.webm
-
-# Before/after comparison — first clip = left/BEFORE, second = right/AFTER
-<demo-dir>/scripts/compose-demo.sh \
-  --output <artifact-dir>/demo.mp4 \
-  --title "PR #51 — Fix flicker on load" \
-  --layout side-by-side --labels "BEFORE (main)" "AFTER (PR)" \
-  /tmp/before/session-before.webm /tmp/after/session-after.webm
-```
-
-Flags: `--title` (required, on the card), `--subtitle`, `--layout
-single|side-by-side`, `--labels A B` (side-by-side), `--speed N`, `--trim
-START:END` (seconds, single layout), `--crf` (default 18 — lower = higher
-quality), `--target-size-mb` (default 10), `--width/--height` (default
-1920×1080), `--title-secs`. The script normalizes (lanczos scale), lays out, adds
-the title card, then does a **quality-first single-pass CRF** encode
-(`+faststart`, `yuv420p`); only if that overshoots `--target-size-mb` does it
-fall back to a size-capped two-pass encode. It prints a JSON summary line:
-`{"output":"…","resolution":"1920x1080","duration":"38.4","size_mb":3.1}`.
-
-## Guardrails — self-check before reporting
-
-Confirm the output with `ffprobe` (the script's summary already reports these):
-
-- **Resolution** matches the requested size (default 1920×1080).
-- **Duration** is sane — not 0s, within a watchable band (~15–90s). Don't crank
-  `--speed` so high (or so low) that the clip becomes a sub-second flash or a
-  near-static crawl; the agent that shipped a 0.2s recording at `--speed 0.05`
-  proved nothing.
-- **Size ≤ 10 MB** so GitHub embeds it inline (25 MB hard limit). The CRF encode
-  usually lands far under this on its own; if it's over, the script auto-falls
-  back to a size-capped encode, but you can also lower `--target-size-mb`, raise
-  `--crf`, or raise `--speed`.
-
-If the recording is too short to be meaningful (a couple of seconds), go back
-and add interaction steps — don't ship a clip that proves nothing.
-
-## Output location
-
-Write `demo.mp4` into the **artifact directory the prompt provides** (the run's
-`.lastlight/<issueKey>/` dir, referenced by the template variable the prompt
-passes). The harness harvests it into the dashboard Artifacts view, and the
-public artifact URL makes it playable inline on GitHub. Do **not** commit the
-mp4 into the repo, and do **not** post it yourself — the workflow embeds it.
-
-Video delivery requires **server-mode build-assets**. If the mp4 can't be
-persisted (no artifact dir provided, or repo-mode), say so in the report and
-describe what the demo showed instead.
-
-## Evidence rules
-
-Mirror `verify`/`browser-qa` — you are demonstrating real behaviour, not selling
-it:
-
-- **Never fake it.** Don't edit the code under test to force a nicer demo, and
-  don't stage a result the feature didn't actually produce.
-- **Show the disambiguating moment** — the thing that only happens if the change
-  works. Off-camera claims don't count.
-- If something doesn't work, the honest demo shows that — report it; don't trim
-  the failure out and call it a success.
-
-## Report
-
-Produce your report as your **final message** — the workflow posts it (don't
-comment yourself). Keep it short:
-
-```
-## Demo: <target>
-
-**Environment:** <branch / commit, package manager, how served, Chromium version>
-
-<one or two sentences: what the video demonstrates and the key moment to watch>
-
-- **Layout:** single | side-by-side
-- **Video:** demo.mp4 (<resolution>, <duration>s, <size>MB)
-
-### Not covered
-<one line: anything the demo doesn't show, and why>
-```
-
-The workflow embeds the playable video from the artifact store; reference it as
-`demo.mp4`. If the browser or compositor was unavailable, say so plainly instead
-of pretending a clip exists.

package/skills/demo/scripts/compose-demo.sh

@@ -1,243 +0,0 @@
-#!/usr/bin/env bash
-# compose-demo.sh — composite a raw browser screen recording into a titled,
-# size-capped demo mp4 using ffmpeg only (NO Remotion, NO headless render).
-#
-# Used by the `/demo` workflow: agent-browser records the session to a .webm,
-# this script turns it into a polished, GitHub-embeddable mp4.
-#
-# Usage:
-#   compose-demo.sh --output demo.mp4 --title "PR #42 — Add dark mode" \
-#     [--subtitle "..."] [--layout single|side-by-side] \
-#     [--labels "BEFORE (main)" "AFTER (PR)"] [--speed 1.5] \
-#     [--trim START:END] [--target-size-mb 10] [--crf 18] \
-#     [--width 1920] [--height 1080] [--title-secs 2.5] <clip1.webm> [clip2.webm]
-#
-# What it does:
-#   1. Normalizes each input clip (optional trim, speed-up, scale+pad to the
-#      panel size with lanczos, fps/pixfmt/SAR normalize, optional per-panel
-#      label).
-#   2. Lays out the body: a single panel, or two panels side-by-side (hstack).
-#   3. Prepends a title/subtitle card (solid bg + drawtext).
-#   4. Quality-first H.264 encode: a single-pass CRF encode (sharp for UI
-#      screencasts) that usually lands well under --target-size-mb; only if it
-#      overshoots does it fall back to a size-targeted two-pass ABR encode.
-#      yuv420p + +faststart for web streaming.
-#   5. Prints an ffprobe summary (resolution / duration / size).
-#
-# Prerequisites: ffmpeg, ffprobe (baked into lastlight-sandbox-qa:latest).
-# Runs fully offline.
-
-set -euo pipefail
-
-die() { echo "compose-demo.sh: error: $*" >&2; exit 1; }
-require_cmd() { command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"; }
-require_cmd ffmpeg
-require_cmd ffprobe
-
-# ── Defaults ────────────────────────────────────────────────────────────────
-OUTPUT=""
-TITLE=""
-SUBTITLE=""
-LAYOUT="single"
-LABEL1=""
-LABEL2=""
-SPEED="1"
-TRIM=""
-TARGET_MB="10"
-CRF="18"
-WIDTH="1920"
-HEIGHT="1080"
-TITLE_SECS="2.5"
-CLIPS=()
-
-# ── Parse args ──────────────────────────────────────────────────────────────
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --output) OUTPUT="$2"; shift 2;;
-    --title) TITLE="$2"; shift 2;;
-    --subtitle) SUBTITLE="$2"; shift 2;;
-    --layout) LAYOUT="$2"; shift 2;;
-    --labels) LABEL1="$2"; LABEL2="$3"; shift 3;;
-    --speed) SPEED="$2"; shift 2;;
-    --trim) TRIM="$2"; shift 2;;
-    --target-size-mb) TARGET_MB="$2"; shift 2;;
-    --crf) CRF="$2"; shift 2;;
-    --width) WIDTH="$2"; shift 2;;
-    --height) HEIGHT="$2"; shift 2;;
-    --title-secs) TITLE_SECS="$2"; shift 2;;
-    -*) die "unknown flag: $1";;
-    *) CLIPS+=("$1"); shift;;
-  esac
-done
-
-[[ -n "$OUTPUT" ]] || die "--output is required"
-[[ ${#CLIPS[@]} -ge 1 ]] || die "at least one input clip is required"
-for c in "${CLIPS[@]}"; do [[ -f "$c" ]] || die "clip not found: $c"; done
-if [[ "$LAYOUT" == "side-by-side" ]]; then
-  [[ ${#CLIPS[@]} -ge 2 ]] || die "side-by-side layout needs two clips"
-fi
-
-WORK="$(mktemp -d "${TMPDIR:-/tmp}/compose-demo-XXXXXX")"
-cleanup() { rm -rf "$WORK"; }
-trap cleanup EXIT
-
-# ── Font for drawtext ────────────────────────────────────────────────────────
-# Prefer an explicit fontfile (Liberation ships in the QA image via
-# fonts-liberation); fall back to fontconfig's default Sans family.
-FONT="${DEMO_FONT:-}"
-if [[ -z "$FONT" ]]; then
-  for f in \
-    /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf \
-    /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf; do
-    [[ -f "$f" ]] && FONT="$f" && break
-  done
-fi
-if [[ -n "$FONT" ]]; then FONTARG="fontfile=${FONT}"; else FONTARG="font=Sans"; fi
-
-# drawtext drives the title card and per-panel labels. The Debian `ffmpeg`
-# package (the QA image) is built with libfreetype so it's present; but degrade
-# gracefully on a build without it (omit text overlays) rather than failing the
-# whole compose — the demo video is still worth shipping.
-HAS_DRAWTEXT=0
-# Detect the drawtext filter WITHOUT a pipe. Under `set -o pipefail`, any
-# `ffmpeg -filters | grep -q drawtext` (or even `printf "$var" | grep -q`) is a
-# false-negative trap: `grep -q` exits on the first match and closes the pipe,
-# the writer (still emitting — `drawtext` sits ~16 KB into ~38 KB of output)
-# dies with SIGPIPE (141), and `pipefail` promotes that to the pipeline's exit
-# status, so the `if` wrongly concludes drawtext is absent (~19 of 20 runs).
-# Capture into a variable and match with a pure bash `case` — no subprocess,
-# no pipe, no SIGPIPE.
-FFMPEG_FILTERS="$(ffmpeg -hide_banner -filters 2>/dev/null || true)"
-case "$FFMPEG_FILTERS" in
-  *drawtext*) HAS_DRAWTEXT=1 ;;
-  *) echo "compose-demo.sh: warning: this ffmpeg lacks the drawtext filter — title card and labels omitted." >&2 ;;
-esac
-
-# Panel size: side-by-side splits the width into two equal panels.
-PH="$HEIGHT"
-if [[ "$LAYOUT" == "side-by-side" ]]; then PW=$(( WIDTH / 2 )); else PW="$WIDTH"; fi
-
-# ── Stage A: normalize one clip into a body panel ─────────────────────────────
-# Args: <input> <outfile> <label-file-or-empty> <apply-trim:0|1>
-build_panel() {
-  local input="$1" outfile="$2" labelfile="$3" apply_trim="$4"
-  local trim_args=()
-  if [[ "$apply_trim" == "1" && -n "$TRIM" ]]; then
-    local start="${TRIM%%:*}" end="${TRIM##*:}"
-    [[ -n "$start" ]] && trim_args+=(-ss "$start")
-    [[ -n "$end" ]] && trim_args+=(-to "$end")
-  fi
-  local vf="setpts=PTS/${SPEED}"
-  vf+=",scale=${PW}:${PH}:force_original_aspect_ratio=decrease:flags=lanczos"
-  vf+=",pad=${PW}:${PH}:(ow-iw)/2:(oh-ih)/2:color=black"
-  vf+=",fps=30,format=yuv420p,setsar=1"
-  if [[ -n "$labelfile" && "$HAS_DRAWTEXT" == "1" ]]; then
-    # Anchor labels to the TOP of the panel. At the bottom they're hidden behind
-    # the browser/GitHub video player's control bar (scrubber + play button).
-    vf+=",drawtext=${FONTARG}:textfile=${labelfile}:x=(w-text_w)/2:y=28"
-    vf+=":fontsize=34:fontcolor=white:box=1:boxcolor=black@0.55:boxborderw=14"
-  fi
-  # `${arr[@]+"${arr[@]}"}` expands to nothing when the array is empty without
-  # tripping `set -u` (an empty `"${arr[@]}"` errors on bash < 4.4, e.g. macOS).
-  ffmpeg -y -loglevel error ${trim_args[@]+"${trim_args[@]}"} -i "$input" \
-    -vf "$vf" -an -c:v libx264 -crf "$CRF" -preset medium "$outfile"
-}
-
-# Per-panel labels (side-by-side) written to files to avoid drawtext escaping.
-LABELFILE1=""; LABELFILE2=""
-if [[ "$LAYOUT" == "side-by-side" ]]; then
-  if [[ -n "$LABEL1" ]]; then LABELFILE1="$WORK/label1.txt"; printf '%s' "$LABEL1" > "$LABELFILE1"; fi
-  if [[ -n "$LABEL2" ]]; then LABELFILE2="$WORK/label2.txt"; printf '%s' "$LABEL2" > "$LABELFILE2"; fi
-fi
-
-echo "compose-demo.sh: normalizing clips (layout=$LAYOUT, speed=${SPEED}x)…" >&2
-build_panel "${CLIPS[0]}" "$WORK/panel0.mp4" "$LABELFILE1" 1
-BODY="$WORK/body.mp4"
-if [[ "$LAYOUT" == "side-by-side" ]]; then
-  build_panel "${CLIPS[1]}" "$WORK/panel1.mp4" "$LABELFILE2" 1
-  # Pad the shorter panel by freezing its last frame so both stay aligned for the
-  # full body. Without this, hstack lets the shorter side end early and go
-  # blank/black — which reads as "the before didn't render".
-  D0="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$WORK/panel0.mp4" || echo 0)"
-  D1="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$WORK/panel1.mp4" || echo 0)"
-  PAD0="$(awk -v a="$D0" -v b="$D1" 'BEGIN{d=b-a; if(d<0)d=0; printf "%.3f", d}')"
-  PAD1="$(awk -v a="$D0" -v b="$D1" 'BEGIN{d=a-b; if(d<0)d=0; printf "%.3f", d}')"
-  ffmpeg -y -loglevel error -i "$WORK/panel0.mp4" -i "$WORK/panel1.mp4" \
-    -filter_complex "[0:v]tpad=stop_mode=clone:stop_duration=${PAD0}[p0];[1:v]tpad=stop_mode=clone:stop_duration=${PAD1}[p1];[p0][p1]hstack=inputs=2,format=yuv420p,setsar=1[v]" \
-    -map "[v]" -an -c:v libx264 -crf "$CRF" -preset medium "$BODY"
-else
-  BODY="$WORK/panel0.mp4"
-fi
-
-# ── Stage B: title card (skipped when drawtext is unavailable) ───────────────
-TITLE_CLIP=""
-TITLE_DUR="0"
-if [[ "$HAS_DRAWTEXT" == "1" ]]; then
-  TITLEFILE="$WORK/title.txt"; printf '%s' "${TITLE:-Demo}" > "$TITLEFILE"
-  TITLE_VF="drawtext=${FONTARG}:textfile=${TITLEFILE}:x=(w-text_w)/2:y=(h/2)-th-10:fontsize=48:fontcolor=white"
-  if [[ -n "$SUBTITLE" ]]; then
-    SUBFILE="$WORK/subtitle.txt"; printf '%s' "$SUBTITLE" > "$SUBFILE"
-    TITLE_VF+=",drawtext=${FONTARG}:textfile=${SUBFILE}:x=(w-text_w)/2:y=(h/2)+10:fontsize=26:fontcolor=0xb0b0b0"
-  fi
-  TITLE_VF+=",format=yuv420p"
-  ffmpeg -y -loglevel error -f lavfi -i "color=c=0x101418:s=${WIDTH}x${HEIGHT}:d=${TITLE_SECS}:r=30" \
-    -vf "$TITLE_VF" -c:v libx264 -crf "$CRF" -preset medium "$WORK/title.mp4"
-  TITLE_CLIP="$WORK/title.mp4"
-  TITLE_DUR="$TITLE_SECS"
-fi
-
-# ── Stage C: (concat title +) body → final mp4 ───────────────────────────────
-# With a title card: concat it ahead of the body. Without: pass the body
-# through (`null`) so the same encode applies either way.
-if [[ -n "$TITLE_CLIP" ]]; then
-  IN_ARGS=(-i "$TITLE_CLIP" -i "$BODY")
-  FILTER='[0:v][1:v]concat=n=2:v=1:a=0[v]'
-else
-  IN_ARGS=(-i "$BODY")
-  FILTER='[0:v]null[v]'
-fi
-
-# Quality-first: a single-pass CRF encode (visually crisp for UI screencasts —
-# constant quality, not a starved average bitrate) usually lands well under the
-# size cap. The old always-two-pass-ABR path starved short, near-static clips
-# down to a few tens of KB; CRF spends the bits the content needs.
-echo "compose-demo.sh: encoding (crf ${CRF}, preset slow)…" >&2
-ffmpeg -y -loglevel error "${IN_ARGS[@]}" \
-  -filter_complex "$FILTER" -map "[v]" -an \
-  -c:v libx264 -crf "$CRF" -preset slow \
-  -pix_fmt yuv420p -movflags +faststart "$OUTPUT"
-
-# Size cap: only if the quality encode overshoots --target-size-mb do we redo it
-# as a size-targeted two-pass ABR encode (keeps it under GitHub's inline limit).
-OUT_BYTES="$(wc -c < "$OUTPUT" | tr -d ' ')"
-CAP_BYTES="$(awk -v mb="$TARGET_MB" 'BEGIN{printf "%d", mb*1024*1024}')"
-if [[ "$OUT_BYTES" -gt "$CAP_BYTES" ]]; then
-  BODY_DUR="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$BODY" || echo 0)"
-  TOTAL_DUR="$(awk -v a="$TITLE_DUR" -v b="$BODY_DUR" 'BEGIN{printf "%.3f", a + b}')"
-  # Target video bitrate (kbit/s) = target_bytes * 8 / duration / 1000, with a
-  # small headroom factor for the muxer; floored so very short clips still encode.
-  BR_K="$(awk -v mb="$TARGET_MB" -v d="$TOTAL_DUR" 'BEGIN{
-    if (d <= 0) d = 1;
-    br = (mb * 1024 * 1024 * 8) / d / 1000 * 0.92;
-    if (br < 200) br = 200;
-    printf "%d", br;
-  }')"
-  PASSLOG="$WORK/ff2pass"
-  echo "compose-demo.sh: crf encode was $(awk -v b="$OUT_BYTES" 'BEGIN{printf "%.1f", b/1024/1024}')MB > ${TARGET_MB}MB cap — re-encoding size-capped (${TOTAL_DUR}s → ${BR_K}kbit/s, two-pass)…" >&2
-  ffmpeg -y -loglevel error "${IN_ARGS[@]}" \
-    -filter_complex "$FILTER" -map "[v]" -an \
-    -c:v libx264 -b:v "${BR_K}k" -pass 1 -passlogfile "$PASSLOG" -preset medium -f mp4 /dev/null
-  ffmpeg -y -loglevel error "${IN_ARGS[@]}" \
-    -filter_complex "$FILTER" -map "[v]" -an \
-    -c:v libx264 -b:v "${BR_K}k" -pass 2 -passlogfile "$PASSLOG" -preset medium \
-    -pix_fmt yuv420p -movflags +faststart "$OUTPUT"
-fi
-
-# ── Stage D: report ───────────────────────────────────────────────────────────
-RES="$(ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0:s=x "$OUTPUT" || echo '?')"
-DUR="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$OUTPUT" || echo '?')"
-BYTES="$(wc -c < "$OUTPUT" | tr -d ' ')"
-MB="$(awk -v b="$BYTES" 'BEGIN{printf "%.2f", b/1024/1024}')"
-echo "compose-demo.sh: wrote $OUTPUT  (${RES}, ${DUR}s, ${MB}MB)" >&2
-# Machine-readable line for the agent to parse.
-echo "{\"output\":\"${OUTPUT}\",\"resolution\":\"${RES}\",\"duration\":\"${DUR}\",\"size_mb\":${MB}}"