lastlight 0.4.0 → 0.6.1

package/plugins/lastlight/skills/lastlight-server/references/env-schema.md

@@ -0,0 +1,103 @@
+# Overlay config reference — `instance/secrets/.env` + `instance/config.yaml`
+
+The server reads config in layers: packaged `config/default.yaml` → overlay
+`instance/config.yaml` → `instance/secrets/.env` env vars → `LASTLIGHT_*` env.
+Secrets stay env-only and out of git. The container entrypoint copies
+`instance/secrets/.env` → `/app/.env` and `instance/secrets/*.pem` → `/app/*.pem`
+(mode 600) at boot, and the overlay is mounted read-only at `/app/instance`.
+
+## `instance/secrets/.env`  (mode 0600)
+
+Write exactly these keys. `WEBHOOK_SECRET` and `ADMIN_SECRET` are random 32-byte
+hex (`openssl rand -hex 32`). Include only the ONE provider key that matches the
+model.
+
+```dotenv
+# ── Last Light — Environment Variables ─────────────────────
+
+# Overlay (this deployment's private config + assets)
+LASTLIGHT_OVERLAY_DIR=/app/instance
+
+# ── GitHub App (required) ────────────────────────────────
+GITHUB_APP_ID=123456
+# PEM lives at instance/secrets/app.pem; the entrypoint symlinks it to /app/app.pem.
+GITHUB_APP_PRIVATE_KEY_PATH=./app.pem
+GITHUB_APP_INSTALLATION_ID=789012
+
+# ── Webhook (required) — must match the GitHub App's webhook secret ──
+WEBHOOK_SECRET=<openssl rand -hex 32>
+
+# ── Domain (used by Caddy for TLS) ───────────────────────
+DOMAIN=lastlight.example.com
+
+# ── Model + provider API key ─────────────────────────────
+LASTLIGHT_MODEL=anthropic/claude-sonnet-4-6
+# Set whichever ONE matches LASTLIGHT_MODEL:
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# ── Admin dashboard ──────────────────────────────────────
+ADMIN_SECRET=<openssl rand -hex 32>
+# Optional — protects /admin with a password (>=8 chars):
+# ADMIN_PASSWORD=...
+
+# ── Slack (optional) ─────────────────────────────────────
+# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_APP_TOKEN=xapp-...
+# SLACK_DELIVERY_CHANNEL=C0123456
+# SLACK_ALLOWED_USERS=U0123,U0456
+```
+
+Notes:
+- `GITHUB_APP_PRIVATE_KEY_PATH=./app.pem` is correct as-is — it's resolved
+  inside the container, not on the host. Just place the file at
+  `instance/secrets/app.pem`.
+- Provider-key detection: `sk-ant-…` is Anthropic; `sk-or-…` is OpenRouter; any
+  other `sk-…` is OpenAI.
+- **Removing** an env var later requires a container *recreate*
+  (`lastlight server start agent`), not just a restart — compose injects
+  `env_file` vars at creation time. Adding/changing one only needs
+  `lastlight server restart agent`.
+
+## `instance/config.yaml`
+
+Non-secret overlay config, merged over `config/default.yaml`. Arrays replace;
+maps deep-merge. Minimum useful content is the managed-repos list:
+
+```yaml
+# Last Light — private deployment overlay config
+# Merged over config/default.yaml at startup. Restart to apply:
+#   lastlight server restart agent
+managedRepos:
+  - owner/repo
+  - owner/another-repo
+```
+
+If there are no repos yet, write `managedRepos: []` and tell the user to add
+entries before the bot will act. You can also override `models`, `variants`,
+`routes`, and `disabled.*` here — see the repo's `config/default.yaml` for the
+full shape.
+
+## `instance/.gitignore`
+
+So the overlay can become a private git repo without leaking secrets:
+
+```gitignore
+secrets/
+*.pem
+```
+
+## `instance/docker-compose.override.yml`  (only if Caddy is disabled)
+
+Write this ONLY when the user opts out of Caddy TLS (they terminate TLS
+elsewhere). Then symlink it into the working dir as `./docker-compose.override.yml`
+(or run `lastlight server setup` / `update`, which ensures the symlink).
+
+```yaml
+# Deployment compose override — this deployment opted out of Caddy TLS.
+services:
+  caddy:
+    profiles:
+      - disabled
+```

package/plugins/lastlight/skills/lastlight-server/references/operations.md

@@ -0,0 +1,60 @@
+# Last Light server — day-2 operations
+
+All commands are **host-local** (run on the server, not over HTTP) and operate
+on the working directory. That directory resolves from `--home` →
+`LASTLIGHT_HOME` → the saved `serverHome` (from `lastlight server setup`) →
+`~/lastlight`.
+
+## Lifecycle
+
+```bash
+lastlight server status            # docker compose ps + core/overlay version drift
+lastlight server start [service]   # docker compose up -d (whole stack, or one service)
+lastlight server stop [service]    # stop one service, or `down` the whole stack
+lastlight server restart [service] # restart (default service: agent)
+```
+
+## Apply config changes
+
+- **Overlay config.yaml or an added/changed `.env` value:**
+  `lastlight server restart agent` — no image rebuild.
+- **Removing an `.env` value:** `lastlight server start agent` (recreate) — a
+  restart can't unset env_file vars injected at container creation.
+- **Code/asset changes** (anything under `src/`, `workflows/`, `skills/`,
+  `agent-context/`, `config/default.yaml`): a full rebuild — `lastlight server
+  update`.
+
+## Redeploy after a code change (the canonical deploy)
+
+```bash
+lastlight server update            # pull core + overlay, build images, recreate, restart sidecars, health-check
+#   flags: --no-core --no-overlay --no-build --yes
+```
+
+This: git-pulls the core repo and the `instance/` overlay, builds the `agent` +
+`sandbox` (+ best-effort `sandbox-qa`) images, `docker compose up -d
+--remove-orphans`, force-restarts the egress sidecars (coredns + nginx + otel),
+and health-checks `http://127.0.0.1:8644/health`.
+
+## Logs & health
+
+```bash
+curl -fsS http://127.0.0.1:8644/health
+lastlight server logs agent --follow          # live harness logs
+lastlight server logs [service] --tail 200 --since 10m
+lastlight server list                          # the lastlight-* containers
+```
+
+## Debug a running instance (over the admin API)
+
+These talk to the instance over HTTP (need `lastlight login` first — see the
+lastlight-client skill):
+
+```bash
+lastlight workflow list [--status s] [--workflow name]
+lastlight workflow log <id> [--follow]
+lastlight session list ; lastlight session log <id> --follow
+lastlight logs search "<text>" [--scope errors|messages|all]
+lastlight approvals list|approve <id>|reject <id>
+lastlight stats [--daily n | --hourly n]
+```

package/sandbox.Dockerfile

@@ -62,6 +62,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && apt-get purge -y python3-pip \
     && rm -rf /var/lib/apt/lists/*
 
+# uv — fast, isolated Python runner for `type: script` (runtime: python) phases.
+# Single static binary; `uv run script.py` honours PEP 723 inline dependency
+# blocks and resolves them into a cached venv (UV_CACHE_DIR is pointed at the
+# shared /cache volume at runtime, mirroring the npm/pnpm/yarn cache wiring).
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh \
+ && uv --version
+
 # Create non-root agent user, UID/GID pinned to 10001 to MATCH the harness
 # `lastlight` user (see Dockerfile: `useradd -u 10001 lastlight`). The
 # entrypoint chowns the bind-mounted workspace to `agent`; per-PR workspaces

package/skills/browser-qa/scripts/agent-browser.mjs

@@ -69,6 +69,13 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 
 const WAIT_TIMEOUT = 10_000; // sane default for waitFor / assertText probes
+// When recording, hold the page open briefly after the last step before closing
+// the context (which flushes the .webm). A bare goto→waitFor→text flow finishes
+// in ~250 ms — too short for Playwright's video to capture a *painted* frame, so
+// the clip can come out blank (the /demo before/after's "before" panel did).
+// Settling lets late paints + async data ("Loading…") resolve and guarantees a
+// watchable tail. Override with --record-settle-ms / LASTLIGHT_RECORD_SETTLE_MS.
+const RECORD_SETTLE_MS = Number(process.env.LASTLIGHT_RECORD_SETTLE_MS) || 1500;
 
 function emit(obj) {
   process.stdout.write(JSON.stringify(obj) + '\n');
@@ -300,6 +307,14 @@ async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
     // the context to close, which flushes the .webm to disk. A save failure is a
     // reported finding, not a fatal run error.
     if (doRecord) {
+      // Settle before closing: let late paints + async data resolve and ensure
+      // the .webm has a watchable, non-blank tail (see RECORD_SETTLE_MS).
+      if (RECORD_SETTLE_MS > 0) {
+        await page
+          .waitForLoadState('networkidle', { timeout: RECORD_SETTLE_MS })
+          .catch(() => {});
+        await page.waitForTimeout(RECORD_SETTLE_MS).catch(() => {});
+      }
       const video = page.video();
       await context.close();
       if (video) {

package/skills/demo/SKILL.md

@@ -95,14 +95,34 @@ node <browser-qa-dir>/scripts/agent-browser.mjs run flow.json \
 # → writes /tmp/demo-cap/session.webm, reports {"video":"…/session.webm", …}
 ```
 
-Pick the viewport to match the layout so the clip isn't letterboxed:
-`1280x720` for `single`; `~960x1000` per panel for `side-by-side` (set it in the
-flow's `viewport`).
+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:
 
-**Before/after comparison:** check out and run each branch in turn (the
-`building` skill), recording the **same** scripted interaction against each —
-`session-before.webm` (base branch) and `session-after.webm` (PR head). Only the
-behaviour should differ.
+```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
 
@@ -114,34 +134,40 @@ Composite the raw recording(s) into the final mp4 with the bundled wrapper:
   --output <artifact-dir>/demo.mp4 \
   --title "PR #42 — Add dark mode toggle" \
   --subtitle "Toggling persists the theme across reloads" \
-  --layout single --speed 1.5 --target-size-mb 5 \
+  --layout single --speed 1.5 \
   /tmp/demo-cap/session.webm
 
-# Before/after comparison
+# 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)" \
-  --target-size-mb 5 \
   /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), `--target-size-mb` (default 5),
-`--width/--height` (default 1280×720), `--title-secs`. The script normalizes,
-lays out, adds the title card, and does a **two-pass** encode to land under the
-size cap (`+faststart`, `yuv420p`). It prints a JSON summary line:
-`{"output":"…","resolution":"1280x720","duration":"38.4","size_mb":3.1}`.
+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-free 1280×720).
-- **Duration** is sane — not 0s, within a watchable band (~15–90s).
-- **Size ≤ 5 MB** so GitHub embeds it inline (25 MB hard limit). If over, re-run
-  with a lower `--target-size-mb` or a higher `--speed`.
+- **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.

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

@@ -9,16 +9,19 @@
 #   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 5] [--width 1280] [--height 720] \
-#     [--title-secs 2.5] <clip1.webm> [clip2.webm]
+#     [--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, fps/pixfmt/SAR normalize, optional per-panel label).
+#      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. Two-pass H.264 encode targeting --target-size-mb so the mp4 lands under
-#      GitHub's inline-embed limit; yuv420p + +faststart for web streaming.
+#   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).
@@ -40,9 +43,10 @@ LABEL1=""
 LABEL2=""
 SPEED="1"
 TRIM=""
-TARGET_MB="5"
-WIDTH="1280"
-HEIGHT="720"
+TARGET_MB="10"
+CRF="18"
+WIDTH="1920"
+HEIGHT="1080"
 TITLE_SECS="2.5"
 CLIPS=()
 
@@ -57,6 +61,7 @@ while [[ $# -gt 0 ]]; do
     --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;;
@@ -94,11 +99,19 @@ if [[ -n "$FONT" ]]; then FONTARG="fontfile=${FONT}"; else FONTARG="font=Sans";
 # 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
-if ffmpeg -hide_banner -filters 2>/dev/null | grep -q 'drawtext'; then
-  HAS_DRAWTEXT=1
-else
-  echo "compose-demo.sh: warning: this ffmpeg lacks the drawtext filter — title card and labels omitted." >&2
-fi
+# 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"
@@ -115,17 +128,19 @@ build_panel() {
     [[ -n "$end" ]] && trim_args+=(-to "$end")
   fi
   local vf="setpts=PTS/${SPEED}"
-  vf+=",scale=${PW}:${PH}:force_original_aspect_ratio=decrease"
+  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
-    vf+=",drawtext=${FONTARG}:textfile=${labelfile}:x=(w-text_w)/2:y=h-th-24"
-    vf+=":fontsize=26:fontcolor=white:box=1:boxcolor=black@0.55:boxborderw=12"
+    # 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 20 -preset veryfast "$outfile"
+    -vf "$vf" -an -c:v libx264 -crf "$CRF" -preset medium "$outfile"
 }
 
 # Per-panel labels (side-by-side) written to files to avoid drawtext escaping.
@@ -140,9 +155,16 @@ 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][1:v]hstack=inputs=2,format=yuv420p,setsar=1[v]" \
-    -map "[v]" -an -c:v libx264 -crf 20 -preset veryfast "$BODY"
+    -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
@@ -159,25 +181,14 @@ if [[ "$HAS_DRAWTEXT" == "1" ]]; then
   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 20 -preset veryfast "$WORK/title.mp4"
+    -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, two-pass size cap, faststart ─────────────
-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;
-}')"
-
+# ── 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 two-pass/faststart encode applies either way.
+# 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]'
@@ -185,16 +196,43 @@ else
   IN_ARGS=(-i "$BODY")
   FILTER='[0:v]null[v]'
 fi
-PASSLOG="$WORK/ff2pass"
-echo "compose-demo.sh: encoding (${TOTAL_DUR}s, target ${TARGET_MB}MB → ${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
+
+# 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 -b:v "${BR_K}k" -pass 2 -passlogfile "$PASSLOG" -preset medium \
+  -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 '?')"

package/workflows/examples/bash-smoke.yaml

@@ -0,0 +1,41 @@
+kind: agent
+name: bash-smoke
+description: "Smoke test for deterministic bash + script phases (run in sandbox)"
+phases:
+  - name: phase_0
+    type: context
+
+  # Deterministic shell command in the sandbox. stdout is captured and exposed
+  # downstream via output_var.
+  - name: emit
+    type: bash
+    command: "echo hello-from-bash"
+    output_var: greeting
+
+  # A second bash phase reads the first phase's output via template substitution
+  # AND via the forwarded LL_OUT_<PHASE> env var.
+  - name: consume
+    type: bash
+    command: "echo template={{phaseOutputs.emit}} ; echo env=$LL_OUT_EMIT"
+
+  # Inline JS via node.
+  - name: js
+    type: script
+    runtime: js
+    script: |
+      console.log("node version:", process.version);
+      console.log("answer:", 6 * 7);
+
+  # Inline Python via uv. The PEP 723 block declares a dependency that uv
+  # resolves from PyPI (pypi.org is on the strict egress allowlist) into a
+  # cached venv. unrestricted_egress is NOT needed for PyPI.
+  - name: py
+    type: script
+    runtime: python
+    timeout_seconds: 120
+    script: |
+      # /// script
+      # dependencies = ["cowsay"]
+      # ///
+      import cowsay
+      cowsay.cow("hello from uv")

package/workflows/prompts/demo.md

@@ -44,11 +44,33 @@ so `doctor` should pass.
 
 ## Workspace + run the app
 
-You are already inside the **{{repo}}** repo at branch {{branch}} — the harness
-pre-cloned it and your cwd is the repo root (no `cd`). Follow the `building`
-skill to install dependencies and start the dev-server in the background; poll
-with `curl` until it answers on `localhost:<port>`. For a before/after demo,
-run each branch in turn and record the same scripted interaction against each.
+You are already inside the **{{repo}}** repo — the harness pre-cloned it and your
+cwd is the repo root (no `cd`){{#if baseBranch}}, **checked out at the PR head
+branch `{{branch}}`**, so the workspace already holds the PR's code: this checkout
+*is* your "after" state{{/if}}. Follow the `building` skill to install
+dependencies and start the dev-server in the background; poll with `curl` until
+it answers on `localhost:<port>`.
+
+{{#if baseBranch}}**This is a PR → record a `side-by-side` before/after.** Record
+the **after** first, straight from the current checkout (`{{branch}}`) — do not
+re-checkout for it. Then record the **before** from the base branch
+`{{baseBranch}}`. The pre-clone is shallow + single-branch, so the base isn't
+present locally yet — fetch it explicitly by ref (never trust an ambiguously
+named local branch):
+
+```
+git fetch --depth 1 origin {{baseBranch}}
+git checkout -B {{baseBranch}}-base FETCH_HEAD
+```
+
+Re-run `building`'s install + restart the dev-server after switching. When you
+composite, the **first** clip is the left/BEFORE panel and the **second** is the
+right/AFTER panel.
+
+**Verify before you ship:** the disambiguating change must actually appear in the
+*after* recording and be absent from the *before* (use the driver's `text`/
+`assertText` to read it on both). If both states look identical, your checkout is
+wrong — STOP and fix it; do not ship a side-by-side that proves nothing.{{/if}}
 
 ## Capture and compose
 

package/workflows/qa-test.yaml

@@ -76,7 +76,7 @@ phases:
   # workflow-level `final_message`. Pure composition — no skills, no repo work.
   - name: synthesize
     label: Summary
-    depends_on: [qa_test]
+    depends_on: [qa_test, qa_browser]
     prompt: prompts/qa-synth.md
     model: "{{models.qa-test}}"
     variant: "{{variants.qa-test}}"

package/workflows/verify.yaml

@@ -74,7 +74,7 @@ phases:
   # workflow-level `final_message`. Pure composition — no skills, no repo work.
   - name: synthesize
     label: Summary
-    depends_on: [verify]
+    depends_on: [verify, verify_browser]
     prompt: prompts/verify-synth.md
     model: "{{models.verify}}"
     variant: "{{variants.verify}}"