@event4u/agent-config 2.23.0 → 2.24.0

package/scripts/ai-video/lib/operator-pick.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# operator-pick.sh — best-of-N selection checkpoint invoked after image
+# render by /video:from-script and /video:scene. Renders a thumbnail
+# contact-sheet PNG of the candidates under a scene, then waits for the
+# operator to write <project>/scenes/<id>/selection.json.
+#
+# Dry-run mode (AIV_DRYRUN=true, default) auto-picks candidate 1 and
+# writes the same selection.json so smoke tests stay unattended.
+#
+# Usage:
+#   operator-pick.sh <project-dir> <scene-id>
+#
+# Inputs:
+#   <project-dir>/scenes/<scene-id>/candidates/*.png   (N>=1 image files)
+#
+# Outputs (stdout, one path per line so callers can capture both):
+#   sheet=<project-dir>/scenes/<scene-id>/contact-sheet.png
+#   selected=<absolute path to locked image>
+#
+# Exit codes:
+#   0   selection.json present, locked image path emitted
+#   2   missing candidates directory or empty
+#   3   selection.json malformed or names an unknown candidate
+#   4   operator declined (selection.json absent in live mode)
+
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  printf 'operator-pick: usage: %s <project-dir> <scene-id>\n' "$0" >&2
+  exit 2
+fi
+
+project_dir="$1"
+scene_id="$2"
+scene_dir="${project_dir}/scenes/${scene_id}"
+cand_dir="${scene_dir}/candidates"
+sheet="${scene_dir}/contact-sheet.png"
+sel_file="${scene_dir}/selection.json"
+
+if [ ! -d "${cand_dir}" ]; then
+  printf 'operator-pick: missing candidate dir: %s\n' "${cand_dir}" >&2
+  exit 2
+fi
+
+# Collect candidates in deterministic order (lexical). Portable to
+# macOS bash 3.2 — no `mapfile`.
+candidates=()
+while IFS= read -r _p; do
+  candidates+=("${_p}")
+done < <(find "${cand_dir}" -maxdepth 1 -type f -name '*.png' | LC_ALL=C sort)
+if [ "${#candidates[@]}" -eq 0 ]; then
+  printf 'operator-pick: no candidate PNGs under %s\n' "${cand_dir}" >&2
+  exit 2
+fi
+
+# Build the contact-sheet PNG via ffmpeg. ceil(sqrt(N)) columns.
+n="${#candidates[@]}"
+cols=1
+while [ $((cols * cols)) -lt "${n}" ]; do cols=$((cols + 1)); done
+
+# ffmpeg's `tile` filter needs an input concat; use `-pattern_type glob`.
+if command -v ffmpeg >/dev/null 2>&1; then
+  ffmpeg -y -loglevel error \
+    -pattern_type glob -i "${cand_dir}/*.png" \
+    -filter_complex "tile=${cols}x0:padding=8:margin=16" \
+    "${sheet}" || {
+      printf 'operator-pick: ffmpeg tile failed; falling back to first candidate as sheet\n' >&2
+      cp "${candidates[0]}" "${sheet}"
+    }
+else
+  # ffmpeg absent (e.g. minimal CI). Copy the first candidate as the sheet.
+  cp "${candidates[0]}" "${sheet}"
+fi
+
+# Dry-run: auto-select candidate 1 and write selection.json verbatim so
+# downstream resume reads it identically to a real operator pick.
+if [ "${AIV_DRYRUN:-true}" = "true" ]; then
+  first="$(basename "${candidates[0]}")"
+  cat > "${sel_file}" <<JSON
+{
+  "selected": "${first}",
+  "reason": "auto-selected by operator-pick.sh (AIV_DRYRUN=true)"
+}
+JSON
+fi
+
+# Wait-loop is not appropriate here — the caller (command file) decides
+# whether to poll or hand back. We assert selection.json exists and
+# resolve it; if missing in live mode, we exit non-zero so the caller
+# can pause and re-invoke.
+if [ ! -f "${sel_file}" ]; then
+  printf 'operator-pick: selection.json absent; write %s with {"selected":"<filename>"} and re-run\n' "${sel_file}" >&2
+  exit 4
+fi
+
+# Read selection.json (jq required — already a hard dep for adapters).
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'operator-pick: jq is required\n' >&2
+  exit 3
+fi
+selected_name="$(jq -r '.selected // empty' "${sel_file}")"
+if [ -z "${selected_name}" ]; then
+  printf 'operator-pick: selection.json missing "selected" field\n' >&2
+  exit 3
+fi
+
+selected_path="${cand_dir}/${selected_name}"
+if [ ! -f "${selected_path}" ]; then
+  printf 'operator-pick: selected candidate not found: %s\n' "${selected_path}" >&2
+  exit 3
+fi
+
+# Also write a stable locked.png symlink/copy at the scene root so the
+# motion step can resolve the locked image without re-reading selection.json.
+locked="${scene_dir}/locked.png"
+cp -f "${selected_path}" "${locked}"
+
+printf 'sheet=%s\n' "${sheet}"
+printf 'selected=%s\n' "${locked}"

package/scripts/ai-video/lib/parse-blueprint.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# parse-blueprint.sh — read a 12-block Cinematic Scene Blueprint
+# from stdin (or a file arg) and emit adapter-contract JSON on
+# stdout. Pure POSIX-compatible bash (no associative arrays, runs
+# on macOS bash 3.2); jq required for JSON safety.
+#
+# Schema: .agent-src.uncompressed/skills/scene-expander/scene-blueprint.schema.yaml
+# Contract: scripts/ai-video/lib/adapter-contract.md
+#
+# Usage:
+#   parse-blueprint.sh < prompt.txt > blueprint.json
+#   parse-blueprint.sh prompt.txt > blueprint.json
+#
+# Exit codes:
+#   0   valid blueprint, JSON emitted on stdout
+#   2   missing required block — name on stderr
+#   3   parse error (unknown block, malformed DURATION, etc.)
+
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || {
+  echo "parse-blueprint: jq required" >&2
+  exit 3
+}
+
+input="${1:-/dev/stdin}"
+[ -r "$input" ] || { echo "parse-blueprint: cannot read $input" >&2; exit 3; }
+
+V_STYLE=""; V_SUBJECT=""; V_ENVIRONMENT=""; V_ACTION=""
+V_CAMERA=""; V_LENS=""; V_LIGHTING=""; V_MOOD=""
+V_DIALOGUE=""; V_AMBIENT_SOUND=""; V_DURATION=""; V_NEGATIVE=""
+
+append_to() {
+  local name="$1"; local line="$2"
+  local cur; eval "cur=\${$name}"
+  if [ -z "$cur" ]; then
+    eval "$name=\$line"
+  else
+    eval "$name=\"\${$name}
+\$line\""
+  fi
+}
+
+set_var() {
+  eval "$1=\$2"
+}
+
+current=""
+while IFS= read -r line || [ -n "$line" ]; do
+  stripped="$(printf '%s' "$line" | sed -E 's/^[[:space:]]*//; s/^\*\*//; s/\*\*[[:space:]]*$//')"
+  label="$(printf '%s' "$stripped" | sed -nE 's/^([A-Z][A-Z ]+)[[:space:]]*:.*$/\1/p')"
+  if [ -n "$label" ]; then
+    key="$(printf '%s' "$label" | tr ' ' '_' | tr '[:lower:]' '[:upper:]')"
+    case "$key" in
+      STYLE|SUBJECT|ENVIRONMENT|ACTION|CAMERA|LENS|LIGHTING|MOOD|DIALOGUE|AMBIENT_SOUND|DURATION|NEGATIVE)
+        current="V_$key"
+        rest="$(printf '%s' "$stripped" | sed -E "s/^${label}[[:space:]]*:[[:space:]]*//")"
+        set_var "$current" "$rest"
+        continue
+        ;;
+    esac
+  fi
+  if [ -n "$current" ] && [ -n "$line" ]; then
+    append_to "$current" "$line"
+  fi
+done < "$input"
+
+for short in STYLE SUBJECT ENVIRONMENT ACTION CAMERA LENS LIGHTING MOOD DURATION NEGATIVE; do
+  eval "v=\$V_$short"
+  if [ -z "$v" ]; then
+    echo "parse-blueprint: missing required block: $short" >&2
+    exit 2
+  fi
+done
+
+if ! printf '%s' "$V_DURATION" | grep -Eq '^[0-9]+(\.[0-9])?$'; then
+  echo "parse-blueprint: DURATION not numeric: $V_DURATION" >&2
+  exit 3
+fi
+
+negative_json="$(printf '%s' "$V_NEGATIVE" | tr ',\n' '\n\n' | sed '/^[[:space:]]*$/d' | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//' | jq -R . | jq -s .)"
+
+to_array_or_null() {
+  if [ -z "$1" ]; then
+    printf '%s' "null"
+  else
+    printf '%s\n' "$1" | sed '/^[[:space:]]*$/d' | jq -R . | jq -s .
+  fi
+}
+dialogue_json="$(to_array_or_null "$V_DIALOGUE")"
+ambient_json="$(to_array_or_null "$V_AMBIENT_SOUND")"
+
+audio_native=false
+if [ "$dialogue_json" != "null" ] || [ "$ambient_json" != "null" ]; then
+  audio_native=true
+fi
+
+jq -n \
+  --arg style       "$V_STYLE" \
+  --arg subject     "$V_SUBJECT" \
+  --arg environment "$V_ENVIRONMENT" \
+  --arg action      "$V_ACTION" \
+  --arg camera      "$V_CAMERA" \
+  --arg lens        "$V_LENS" \
+  --arg lighting    "$V_LIGHTING" \
+  --arg mood        "$V_MOOD" \
+  --argjson dialogue "$dialogue_json" \
+  --argjson ambient  "$ambient_json" \
+  --argjson duration "$V_DURATION" \
+  --argjson negative "$negative_json" \
+  --argjson native   "$audio_native" \
+  '{
+    prompt: {
+      style: $style, subject: $subject, environment: $environment,
+      action: $action, camera: $camera, lens: $lens,
+      lighting: $lighting, mood: $mood
+    },
+    audio: { dialogue: $dialogue, ambient: $ambient, enable_native_audio: $native },
+    duration: $duration,
+    negative: $negative,
+    requires: { audio_native: $native }
+  }'

package/scripts/ai-video/lib/redact.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# scripts/ai-video/lib/redact.sh — secret-scrubbing helper for /video:* adapters.
+#
+# Sourced by every adapter under scripts/ai-video/adapters/*.sh. Provides
+# two helpers:
+#
+#   aiv_redact_register <secret>   — register a string to scrub (idempotent)
+#   aiv_redact <text>              — print text with every registered
+#                                    secret replaced by ***REDACTED***
+#
+# Iron Law: an API key must never reach stdout/stderr verbatim. Adapters
+# pipe every network response, curl error, and trace through aiv_redact
+# before printing. Empty / unset values are skipped silently — an unset
+# secret cannot leak.
+#
+# Pure bash, no external dependencies. Safe under `set -euo pipefail`.
+
+# Guard against double-source.
+if [ -n "${AIV_REDACT_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+AIV_REDACT_LOADED=1
+
+# Registry of secrets to scrub. Newline-separated; populated by
+# aiv_redact_register. Never echoed.
+AIV_REDACT_SECRETS=""
+
+aiv_redact_register() {
+  local secret="${1:-}"
+  # Treat empty / placeholder values as no-op so adapters can call this
+  # unconditionally without leaking the placeholder string.
+  case "${secret}" in
+    ""|"REPLACE-ME"|*"-REPLACE-ME") return 0 ;;
+  esac
+  # Require a minimum length so single characters do not nuke the log.
+  if [ "${#secret}" -lt 8 ]; then
+    return 0
+  fi
+  # Idempotent — skip if already registered.
+  case "${AIV_REDACT_SECRETS}" in
+    *"${secret}"*) return 0 ;;
+  esac
+  AIV_REDACT_SECRETS="${AIV_REDACT_SECRETS}${secret}
+"
+}
+
+aiv_redact() {
+  local input
+  if [ "$#" -gt 0 ]; then
+    input="$*"
+  else
+    input="$(cat)"
+  fi
+  if [ -z "${AIV_REDACT_SECRETS}" ]; then
+    printf '%s\n' "${input}"
+    return 0
+  fi
+  # Apply replacements one secret at a time using awk so special chars
+  # in the secret cannot break a sed expression. Use a here-string to
+  # avoid running the loop in a subshell (which would discard mutations
+  # to ${input}).
+  local secret
+  while IFS= read -r secret; do
+    [ -z "${secret}" ] && continue
+    input="$(printf '%s' "${input}" | awk -v s="${secret}" '
+      {
+        out = ""
+        rest = $0
+        while ((i = index(rest, s)) > 0) {
+          out = out substr(rest, 1, i - 1) "***REDACTED***"
+          rest = substr(rest, i + length(s))
+        }
+        print out rest
+      }')"
+  done <<< "${AIV_REDACT_SECRETS}"
+  printf '%s\n' "${input}"
+}
+
+# Convenience wrapper: pipe stdin through aiv_redact line by line so
+# adapters can do `curl … 2>&1 | aiv_redact_stream`.
+aiv_redact_stream() {
+  while IFS= read -r line; do
+    aiv_redact "${line}"
+  done
+}

package/scripts/ai-video/lib/validate-deps.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# validate-deps.sh — startup validator invoked by every /video:* command
+# BEFORE any adapter or network call. Reads the YAML frontmatter from
+# the command file, resolves every declared persona + skill against
+# .agent-src/personas/ and .agent-src/skills/, and fails fast with the
+# missing-id list.
+#
+# Scope (per roadmap Phase 5 Step 5): existence + frontmatter `id` match
+# only. No version pinning (scope-control § rules); no schema validation
+# of persona / skill bodies — that lives in `task lint-skills`.
+#
+# Usage:
+#   validate-deps.sh <path-to-command.md>
+#
+# Exit codes:
+#   0   all declared personas + skills resolve
+#   2   command file missing or no frontmatter
+#   3   one or more declared ids do not resolve (list on stderr)
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+  printf 'validate-deps: usage: %s <path-to-command.md>\n' "$0" >&2
+  exit 2
+fi
+
+cmd_file="$1"
+if [ ! -f "${cmd_file}" ]; then
+  printf 'validate-deps: command file not found: %s\n' "${cmd_file}" >&2
+  exit 2
+fi
+
+# Resolve repo root from this script's location (scripts/ai-video/lib/).
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/../../.." && pwd)"
+
+# AIV_PERSONAS_DIR / AIV_SKILLS_DIR allow overrides for tests; defaults
+# point at the generated mirrors (skills+personas live there at runtime).
+personas_dir="${AIV_PERSONAS_DIR:-${repo_root}/.agent-src/personas}"
+skills_dir="${AIV_SKILLS_DIR:-${repo_root}/.agent-src/skills}"
+
+# Extract the frontmatter block (between the first two `---` lines).
+fm="$(awk '
+  BEGIN { in_fm=0; count=0 }
+  /^---[[:space:]]*$/ { count++; if (count==1) { in_fm=1; next } if (count==2) { exit } }
+  in_fm { print }
+' "${cmd_file}")"
+
+if [ -z "${fm}" ]; then
+  printf 'validate-deps: no YAML frontmatter in %s\n' "${cmd_file}" >&2
+  exit 2
+fi
+
+# Parse `personas:` and `skills:` lines. We accept inline-list form only
+# (the template we ship), e.g. `personas: [a, b]`. No multi-line block
+# form — keeps the validator dependency-free (no yq / python).
+_extract_list() {
+  # $1 = key name (personas|skills)
+  printf '%s\n' "${fm}" \
+    | awk -v key="$1" '
+        $0 ~ "^" key ":" {
+          line=$0
+          sub("^" key ":[[:space:]]*", "", line)
+          sub("^\\[", "", line)
+          sub("\\][[:space:]]*$", "", line)
+          gsub(",", " ", line)
+          print line
+        }' \
+    | tr -s ' ' '\n' \
+    | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' \
+    | sed '/^$/d'
+}
+
+# Portable to macOS bash 3.2 — no `mapfile`.
+personas=()
+while IFS= read -r _id; do
+  personas+=("${_id}")
+done < <(_extract_list personas)
+skills=()
+while IFS= read -r _id; do
+  skills+=("${_id}")
+done < <(_extract_list skills)
+
+missing=()
+
+# bash 3.2 treats `"${arr[@]}"` on an empty array as unbound under
+# `set -u`. Guard each loop with the length check.
+
+# A persona is "present" if .agent-src/personas/<id>.md exists OR
+# .agent-src/personas/<id>/persona.md exists (template-specialist shape).
+if [ "${#personas[@]}" -gt 0 ]; then
+for p in "${personas[@]}"; do
+  [ -z "${p}" ] && continue
+  if [ ! -f "${personas_dir}/${p}.md" ] && [ ! -f "${personas_dir}/${p}/persona.md" ]; then
+    missing+=("persona:${p}")
+    continue
+  fi
+  # Frontmatter id match: read `id:` (optional) or `name:` from the
+  # persona file; if present it must equal the declared slug.
+  src_file="${personas_dir}/${p}.md"
+  [ -f "${src_file}" ] || src_file="${personas_dir}/${p}/persona.md"
+  declared_id="$(awk '/^id:[[:space:]]*/ { sub("^id:[[:space:]]*", ""); print; exit } /^name:[[:space:]]*/ { sub("^name:[[:space:]]*", ""); print; exit }' "${src_file}" | tr -d '"' | tr -d "'")"
+  if [ -n "${declared_id}" ] && [ "${declared_id}" != "${p}" ]; then
+    missing+=("persona:${p} (file declares id=${declared_id})")
+  fi
+done
+fi
+
+# A skill is "present" if .agent-src/skills/<id>/SKILL.md exists.
+if [ "${#skills[@]}" -gt 0 ]; then
+for s in "${skills[@]}"; do
+  [ -z "${s}" ] && continue
+  skill_file="${skills_dir}/${s}/SKILL.md"
+  if [ ! -f "${skill_file}" ]; then
+    missing+=("skill:${s}")
+    continue
+  fi
+  declared_id="$(awk '/^name:[[:space:]]*/ { sub("^name:[[:space:]]*", ""); print; exit }' "${skill_file}" | tr -d '"' | tr -d "'")"
+  if [ -n "${declared_id}" ] && [ "${declared_id}" != "${s}" ]; then
+    missing+=("skill:${s} (file declares name=${declared_id})")
+  fi
+done
+fi
+
+if [ "${#missing[@]}" -gt 0 ]; then
+  printf 'validate-deps: unresolved declarations in %s:\n' "${cmd_file}" >&2
+  printf '  - %s\n' "${missing[@]}" >&2
+  exit 3
+fi
+
+# Silent success — callers can `set -e` and continue.
+exit 0

package/scripts/ai-video/stitch.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# stitch.sh — ffmpeg-based clip concatenator for /video:* pipelines.
+#
+# Drives the cut from <project>/manifest.json (an ordered array of
+# `{scene_id, clip_path, audio_embedded, audio_path?, duration}`).
+# Pass-through for audio_embedded=true; ffmpeg mux for audio_embedded
+# =false; operator-supplied bed for video-only clips.
+#
+# Usage:
+#   stitch.sh <manifest.json> <output.mp4>
+#               [--skip-scene <id> ...]
+#               [--abort-on-missing | --continue]
+#               [--crossfade <seconds>]
+#
+# Failure semantics:
+#   - Missing clip → fail loud with scene_id and re-render hint
+#     unless --skip-scene <id> drops the clip from the cut or
+#     --continue is passed (the dropped scenes are written to stderr).
+#   - --abort-on-missing is the default.
+#   - Adapter-failure rollback contract: a failed adapter writes
+#     <project>/scenes/<id>/error.json; stitch.sh checks for that
+#     file alongside the clip and surfaces it instead of an opaque
+#     ffmpeg error.
+
+set -euo pipefail
+
+# shellcheck source=lib/adapter-common.sh
+. "$(dirname "$0")/lib/adapter-common.sh"
+
+aiv_require_cmd jq
+
+DRYRUN="${AIV_DRYRUN:-true}"
+case "${DRYRUN}" in
+  false|FALSE|0|no|NO) DRYRUN_FLAG=0 ;;
+  *) DRYRUN_FLAG=1 ;;
+esac
+[ "${DRYRUN_FLAG}" -eq 0 ] && aiv_require_cmd ffmpeg
+
+MANIFEST="${1:-}"
+OUTPUT="${2:-}"
+[ -n "${MANIFEST}" ] && [ -n "${OUTPUT}" ] \
+  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--skip-scene <id>] [--abort-on-missing|--continue] [--crossfade <s>]"
+[ -r "${MANIFEST}" ] || aiv_die 2 "manifest not readable: ${MANIFEST}"
+shift 2 || true
+
+SKIP_IDS=""
+MISSING_POLICY="abort"
+CROSSFADE=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --skip-scene) SKIP_IDS="${SKIP_IDS} ${2:-}"; shift 2 ;;
+    --abort-on-missing) MISSING_POLICY="abort"; shift ;;
+    --continue) MISSING_POLICY="continue"; shift ;;
+    --crossfade) CROSSFADE="${2:-}"; shift 2 ;;
+    *) aiv_die 2 "stitch.sh: unknown flag '$1'" ;;
+  esac
+done
+
+skip_match() {
+  local id="$1" s
+  for s in ${SKIP_IDS}; do
+    [ "${s}" = "${id}" ] && return 0
+  done
+  return 1
+}
+
+PROJECT_DIR="$(cd "$(dirname "${MANIFEST}")" && pwd)"
+WORK_DIR="$(mktemp -d -t aiv-stitch-XXXXXX)"
+trap 'rm -rf "${WORK_DIR}"' EXIT
+CONCAT_LIST="${WORK_DIR}/concat.txt"
+: > "${CONCAT_LIST}"
+
+# Accept both bare-array manifests and the documented object shape
+# (`{ "scenes": [...] }`). Field names tolerate the legacy
+# `scene_id` / `clip_path` keys and the example `id` / `expected_clip`.
+SCENES_JQ='if type == "array" then .[] else .scenes[] end'
+
+count=0
+missing=0
+plan=""
+while IFS= read -r row; do
+  [ -n "${row}" ] || continue
+  scene_id="$(printf '%s' "${row}" | jq -r '.scene_id // .id')"
+  clip_path="$(printf '%s' "${row}" | jq -r '.clip_path // .expected_clip')"
+  audio_embedded="$(printf '%s' "${row}" | jq -r '.audio_embedded // false')"
+  audio_path="$(printf '%s' "${row}" | jq -r '.audio_path // empty')"
+
+  case "${clip_path}" in
+    /*) ;;
+    *) clip_path="${PROJECT_DIR}/${clip_path}" ;;
+  esac
+
+  if skip_match "${scene_id}"; then
+    printf 'stitch: skip scene=%s (operator --skip-scene)\n' "${scene_id}" >&2
+    continue
+  fi
+
+  if [ "${DRYRUN_FLAG}" -eq 1 ]; then
+    plan="${plan}${scene_id}\taudio_embedded=${audio_embedded}\t${clip_path}\n"
+    count=$((count + 1))
+    continue
+  fi
+
+  if [ ! -f "${clip_path}" ]; then
+    err_json="${PROJECT_DIR}/scenes/${scene_id}/error.json"
+    if [ -f "${err_json}" ]; then
+      printf 'stitch: scene=%s adapter-error: ' "${scene_id}" >&2
+      jq -r '"adapter=\(.adapter) exit=\(.exit_code) user_action=\(.user_action)"' "${err_json}" >&2
+    fi
+    if [ "${MISSING_POLICY}" = "continue" ]; then
+      printf 'stitch: continue past missing scene=%s clip=%s (re-render or --skip-scene next time)\n' \
+        "${scene_id}" "${clip_path}" >&2
+      missing=$((missing + 1))
+      continue
+    fi
+    aiv_die 7 "missing clip for scene=${scene_id} at ${clip_path} (re-render the scene, pass --skip-scene ${scene_id}, or use --continue)"
+  fi
+
+  # For clips without embedded audio that ship a sibling track, mux
+  # via ffmpeg into a tmp file before concat. Pure pass-through for
+  # the embedded-audio case.
+  if [ "${audio_embedded}" = "false" ] && [ -n "${audio_path}" ] && [ -f "${audio_path}" ]; then
+    muxed="${WORK_DIR}/${scene_id}.mp4"
+    ffmpeg -loglevel error -y -i "${clip_path}" -i "${audio_path}" \
+      -c:v copy -c:a aac -shortest "${muxed}" >/dev/null \
+      || aiv_die 8 "ffmpeg mux failed for scene=${scene_id}"
+    printf "file '%s'\n" "${muxed}" >> "${CONCAT_LIST}"
+  else
+    printf "file '%s'\n" "${clip_path}" >> "${CONCAT_LIST}"
+  fi
+  count=$((count + 1))
+done <<EOF
+$(jq -c "${SCENES_JQ}" "${MANIFEST}")
+EOF
+
+[ "${count}" -gt 0 ] || aiv_die 7 "stitch: no usable clips after manifest scan (missing=${missing}, skipped via --skip-scene)"
+
+if [ "${DRYRUN_FLAG}" -eq 1 ]; then
+  printf 'stitch: dry-run plan (output=%s, scenes=%d):\n' "${OUTPUT}" "${count}" >&2
+  printf '%b' "${plan}" >&2
+  printf '{"output":"%s","scenes":%d,"missing":0,"dry_run":true}\n' "${OUTPUT}" "${count}"
+  exit 0
+fi
+
+if [ -n "${CROSSFADE}" ]; then
+  printf 'stitch: crossfade=%ss requested — passing through ffmpeg xfade filter not yet implemented (concat path used)\n' \
+    "${CROSSFADE}" >&2
+fi
+
+ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
+  -c copy "${OUTPUT}" >/dev/null \
+  || aiv_die 8 "ffmpeg concat failed (manifest=${MANIFEST}, output=${OUTPUT})"
+
+printf '{"output":"%s","scenes":%d,"missing":%d}\n' "${OUTPUT}" "${count}" "${missing}"