Upload batch 65: 500 files (0.01 GiB)

tools/run_confidence_validation25_reference_single.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$#" -ne 5 ]]; then
+  echo "Usage: $0 EVAL_NAME CONFIDENCE_CHECKPOINT REPLACE_STEPS THRESHOLD_MODE THRESHOLD" >&2
+  echo "THRESHOLD_MODE must be global or per_step." >&2
+  exit 2
+fi
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+eval_name="$1"
+confidence_checkpoint="$2"
+replace_steps="$3"
+threshold_mode="$4"
+threshold="$5"
+
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay_july20260720/bin/python}"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-${repo_root}/datasets/${dataset_name}}"
+validation_root="${dataset_root}/validation"
+eval_root="${dataset_root}/evaluations/${eval_name}"
+log_dir="${eval_root}/logs"
+base_model="${PREDICTOR_BASE_MODEL:-${repo_root}/outputs/hf_snapshot_repaired_9b49404}"
+action_ckpt="${PREDICTOR_ACTION_CKPT:-/mnt/local_nvme/cz/checkpoints/hy_worldplay/huggingface/hub/models--tencent--HY-WorldPlay/snapshots/f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/diffusion_pytorch_model.safetensors}"
+weights="${repo_root}/checkpoints/predictor_v4_prefeature_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors"
+
+if [[ ! "${eval_name}" =~ ^[A-Za-z0-9._-]+$ ]]; then
+  echo "Invalid eval name: ${eval_name}" >&2
+  exit 2
+fi
+if [[ "${replace_steps}" != "1,2" && "${replace_steps}" != "1,2,3" ]]; then
+  echo "replace_steps must be 1,2 or 1,2,3" >&2
+  exit 2
+fi
+if [[ "${threshold_mode}" != "global" && "${threshold_mode}" != "per_step" ]]; then
+  echo "threshold mode must be global or per_step" >&2
+  exit 2
+fi
+
+[[ -x "${python_bin}" ]]
+[[ -d "${base_model}" ]]
+[[ -f "${action_ckpt}" ]]
+[[ -f "${weights}" ]]
+[[ -f "${confidence_checkpoint}" ]]
+[[ -f "${validation_root}/cases.jsonl" ]]
+[[ $(find "${validation_root}/input_images" -type f -name '*.jpg' | wc -l) -eq 25 ]]
+[[ $(find "${validation_root}/full" -type f -name '*.mp4' | wc -l) -eq 100 ]]
+
+mkdir -p "${log_dir}"
+export PYTHONPATH="${repo_root}"
+export HY_PROFILE_TIMING=1
+
+confidence_args=(--confidence_checkpoint "${confidence_checkpoint}")
+if [[ "${threshold_mode}" == "global" ]]; then
+  confidence_args+=(--confidence_threshold "${threshold}")
+else
+  confidence_args+=(--confidence_thresholds "${threshold}")
+fi
+
+run_workers() {
+  local phase="$1"
+  shift
+  local -a pids=()
+  local worker_id pid failed=0
+  for worker_id in $(seq 0 7); do
+    CUDA_VISIBLE_DEVICES="${worker_id}" "${python_bin}" -u "$@" \
+      --worker_id "${worker_id}" --num_workers 8 \
+      >"${log_dir}/${phase}_worker_${worker_id}.log" 2>&1 &
+    pid="$!"
+    pids+=("${pid}")
+    echo "${pid}" >"${log_dir}/${phase}_worker_${worker_id}.pid"
+  done
+  for pid in "${pids[@]}"; do
+    if ! wait "${pid}"; then failed=1; fi
+  done
+  if [[ "${failed}" -ne 0 ]]; then
+    echo "${phase} worker failure; inspect ${log_dir}/${phase}_worker_*.log" >&2
+    return 1
+  fi
+}
+
+if [[ ! -f "${eval_root}/generation.completed" ]] \
+  || [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' 2>/dev/null | wc -l) -ne 100 ]]; then
+  date -u +%FT%TZ >"${eval_root}/generation.started"
+  run_workers generate \
+    "${repo_root}/tools/generate_predictor_v4_train_case_eval.py" \
+    --dataset_root "${validation_root}" \
+    --output_root "${eval_root}" \
+    --base_model "${base_model}" \
+    --action_ckpt "${action_ckpt}" \
+    --weights "${weights}" \
+    --source_blocks 1,52 \
+    --predictor_variant v4 \
+    --previous_condition_mode same_step \
+    --replace_steps "${replace_steps}" \
+    --modes predictor \
+    "${confidence_args[@]}"
+  [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' | wc -l) -eq 100 ]]
+  date -u +%FT%TZ >"${eval_root}/generation.completed"
+else
+  echo "[skip] generation already complete: ${eval_name}"
+fi
+
+metric_records=0
+if [[ -f "${eval_root}/metrics.json" ]]; then
+  metric_records=$("${python_bin}" -c \
+    'import json,sys; print(len(json.load(open(sys.argv[1]))["records"]))' \
+    "${eval_root}/metrics.json")
+fi
+if [[ ! -f "${eval_root}/metrics.completed" || "${metric_records}" -ne 100 ]]; then
+  date -u +%FT%TZ >"${eval_root}/metrics.started"
+  run_workers metrics \
+    "${repo_root}/tools/compute_predictor_v4_train_case_metrics.py" \
+    --dataset_root "${validation_root}" \
+    --output_root "${eval_root}" \
+    --num_cases 25 \
+    --reference_subdir full \
+    --modes predictor \
+    --metric_batch_size 4
+  "${python_bin}" "${repo_root}/tools/merge_predictor_v4_train_case_metrics.py" \
+    --output_root "${eval_root}" \
+    --num_workers 8 \
+    --num_cases 25 \
+    --modes predictor \
+    --replace_steps "${replace_steps}" \
+    --reference_label "Full-DiT validation videos" \
+    >"${log_dir}/metrics_merge.log" 2>&1
+  [[ $("${python_bin}" -c \
+    'import json,sys; print(len(json.load(open(sys.argv[1]))["records"]))' \
+    "${eval_root}/metrics.json") -eq 100 ]]
+  date -u +%FT%TZ >"${eval_root}/metrics.completed"
+else
+  echo "[skip] metrics already complete: ${eval_name}"
+fi
+
+date -u +%FT%TZ >"${eval_root}/sync.completed"
+if [[ "${PREDICTOR_SKIP_SYNC:-1}" != "1" ]]; then
+  bucket="${BUCKET:-s3-us-west2-default}"
+  durable_eval_uri="s3://${bucket}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/evaluations/${eval_name}"
+  aws s3 sync "${eval_root}" "${durable_eval_uri}" --only-show-errors
+fi
+
+echo "Validation evaluation complete: ${eval_root}"

tools/run_offline_ffff_targets_validation25_evaluation.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+vbench_repo="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/VBench"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/${dataset_name}}"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+weights="${repo_root}/checkpoints/predictor_v4_detached-chunk-timestep-rollout-offline-ffff-targets-fppp_blocks1-52_fulltrain100_seed20260721_fp32master_8gpu_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1_swanlab/predictor_step_02000.safetensors"
+eval_prefix="eval_validation25_detached-chunk-timestep-rollout-offline-ffff-targets-fppp-fulltrain100"
+eval_suffix="blocks1-52_ckptstep2000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1"
+fppf_name="${eval_prefix}_schedule-fppf_${eval_suffix}"
+fppp_name="${eval_prefix}_schedule-fppp_${eval_suffix}"
+run_name="validation25_offline_ffff_targets_step2000"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/${run_name}"
+
+export PYTHONPATH="${repo_root}"
+
+bash "${repo_root}/tools/launch_vbench_validation_predictor.sh" \
+  "${fppf_name}" "${weights}" "1,52" v4 "1,2"
+bash "${repo_root}/tools/launch_vbench_validation_predictor.sh" \
+  "${fppp_name}" "${weights}" "1,52" v4 "1,2,3"
+
+export PYTHONPATH="${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/vbench"
+export TORCH_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/torch"
+export HF_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/huggingface"
+
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+group_fppf="offline_ffff_targets_step2000_fppf"
+group_fppp="offline_ffff_targets_step2000_fppp"
+declare -a groups=(
+  "${group_fppf}|${dataset_root}/evaluations/${fppf_name}/predictor"
+  "${group_fppp}|${dataset_root}/evaluations/${fppp_name}/predictor"
+)
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  video_count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  if [[ "${video_count}" -ne 100 ]]; then
+    echo "${label}: expected 100 videos, found ${video_count}: ${source_dir}" >&2
+    exit 1
+  fi
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+
+staged_count=$(find "${staging_root}" -maxdepth 1 -type l | wc -l)
+if [[ "${staged_count}" -ne 200 ]]; then
+  echo "Expected 200 staged videos, found ${staged_count}" >&2
+  exit 1
+fi
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count 200
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json
+import sys
+
+path, dimension = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == 200, (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  --group "${group_fppf}" \
+  --group "${group_fppp}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+echo "[validation] all standard and VBench metrics complete: ${run_root}"

tools/run_oldenv_validation_reruns_sequential.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay_july20260720/bin/python}"
+base_model="${PREDICTOR_BASE_MODEL:-${repo_root}/outputs/hf_snapshot_repaired_9b49404}"
+run_tag="${OLDENV_REVAL_TAG:-oldenv_reval_20260821}"
+run_root="${repo_root}/logs/${run_tag}"
+master_log="${run_root}/sequential.log"
+status_file="${run_root}/status.tsv"
+
+mkdir -p "${run_root}"
+exec > >(tee -a "${master_log}") 2>&1
+
+export PREDICTOR_PYTHON_BIN="${python_bin}"
+export PREDICTOR_BASE_MODEL="${base_model}"
+export PREDICTOR_SKIP_SYNC="${PREDICTOR_SKIP_SYNC:-0}"
+export PYTHONPATH="${repo_root}"
+
+on_error() {
+  local exit_code="$?"
+  printf 'failed\t%s\tline=%s\texit=%s\n' "$(date -u +%FT%TZ)" "${BASH_LINENO[0]}" "${exit_code}" >>"${status_file}"
+  exit "${exit_code}"
+}
+trap on_error ERR
+
+record_status() {
+  printf '%s\t%s\t%s\n' "$1" "$(date -u +%FT%TZ)" "$2" >>"${status_file}"
+}
+
+run_confidence_eval() {
+  local short_name="$1" checkpoint="$2" replace_steps="$3" threshold_mode="$4" threshold="$5"
+  local eval_name="eval_validation25_${short_name}_${run_tag}"
+  record_status start "${eval_name}"
+  bash "${repo_root}/tools/run_confidence_validation25_reference_single.sh" \
+    "${eval_name}" "${checkpoint}" "${replace_steps}" "${threshold_mode}" "${threshold}"
+  record_status complete "${eval_name}"
+}
+
+echo "[preflight] fixed environment"
+"${python_bin}" - <<'PY'
+import importlib.util
+import torch
+assert torch.__version__ == "2.6.0+cu124", torch.__version__
+assert importlib.util.find_spec("flash_attn") is None, "flash_attn must be absent"
+print(f"torch={torch.__version__} cuda={torch.version.cuda} flash_attn=False")
+PY
+[[ -d "${base_model}" ]]
+[[ $(find "${repo_root}/datasets/hyworldplay_predictor_vbench_val25_test50/validation/full" -type f -name '*.mp4' | wc -l) -eq 100 ]]
+record_status preflight "torch=2.6.0+cu124; flash_attn=False"
+
+small_c1="${repo_root}/confidence_validation/checkpoints/confidence_c1.pt"
+wide_c1="${repo_root}/confidence_validation_wide4096x2_c1/checkpoints/confidence_c1.pt"
+wide_c2="${repo_root}/confidence_validation_wide4096x2_c2/checkpoints/confidence_c2.pt"
+
+# Keep the trained thresholds unchanged. The fixed-environment run records the
+# actual fallback count, so distribution drift remains visible in the result.
+run_confidence_eval stage1-c1-threshold-r10 "${small_c1}" 1,2,3 global -3.523588657
+run_confidence_eval stage1-c1-threshold-r25 "${small_c1}" 1,2,3 global -3.915276289
+run_confidence_eval stage1-c1-threshold-r33 "${small_c1}" 1,2,3 global -4.329442501
+run_confidence_eval stage1-c1-threshold-r50 "${small_c1}" 1,2,3 global -4.798926830
+run_confidence_eval stage1-wide4096x2-c1-threshold-r33 "${wide_c1}" 1,2,3 global -4.308430990
+run_confidence_eval stage1-wide4096x2-c2-hybrid-p3full-p12r10 "${wide_c2}" 1,2 per_step 1:-4.136674309,2:-3.798280764
+run_confidence_eval stage1-wide4096x2-c2-hybrid-p3full-p12r25 "${wide_c2}" 1,2 per_step 1:-4.400576830,2:-4.049407601
+
+record_status complete "all validation reruns"
+date -u +%FT%TZ >"${run_root}/all.completed"
+
+if [[ "${PREDICTOR_SKIP_SYNC}" != "1" ]]; then
+  bucket="${BUCKET:-s3-us-west2-default}"
+  aws s3 sync "${run_root}" \
+    "s3://${bucket}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/logs/${run_tag}" \
+    --only-show-errors
+fi
+
+echo "[complete] all fixed-environment validation reruns"

tools/run_predictor_confidence_experiment.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+PYTHON_BIN="${PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay_runtime/bin/python}"
+GPU_IDS="${GPU_IDS:-0,1,2,3,4,5,6,7}"
+NPROC="${NPROC:-8}"
+TRAIN_ROOT="${TRAIN_ROOT:-$ROOT/datasets/hyworldplay_predictor_prefeature_v4}"
+VAL_ROOT="${VAL_ROOT:-$ROOT/datasets/hyworldplay_predictor_confidence_validation25_prefeature}"
+FEATURE_ROOT="${FEATURE_ROOT:-$ROOT/confidence_validation/features}"
+OUTPUT_ROOT="${OUTPUT_ROOT:-$ROOT/confidence_validation}"
+PREDICTOR="${PREDICTOR:-$ROOT/checkpoints/predictor_v4_prefeature_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors}"
+BASE_MODEL="${BASE_MODEL:-$ROOT/outputs/model_cache_repaired/HunyuanVideo-1.5-9b49404-v2}"
+TEACHER="${TEACHER:-/mnt/local_nvme/cz/checkpoints/hy_worldplay/huggingface/hub/models--tencent--HY-WorldPlay/snapshots/f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/diffusion_pytorch_model.safetensors}"
+export PYTHONPATH="$ROOT"
+
+if [[ ! -f "$VAL_ROOT/train_eval_manifest.jsonl" ]]; then
+  "$PYTHON_BIN" tools/prepare_confidence_validation_prefeature.py --output_root "$VAL_ROOT"
+  mkdir -p "$VAL_ROOT/logs"
+  pids=()
+  for worker in $(seq 0 $((NPROC - 1))); do
+    CUDA_VISIBLE_DEVICES="${worker}" "$PYTHON_BIN" -u tools/build_predictor_prefeature_dataset.py \
+      --dataset_root "$VAL_ROOT" --base_model "$BASE_MODEL" --action_ckpt "$TEACHER" \
+      --worker_id "$worker" --num_workers "$NPROC" \
+      >"$VAL_ROOT/logs/worker_${worker}.log" 2>&1 &
+    pids+=("$!")
+  done
+  failed=0
+  for worker in "${!pids[@]}"; do
+    wait "${pids[$worker]}" || { echo "validation trajectory worker $worker failed" >&2; failed=1; }
+  done
+  (( failed == 0 )) || exit 1
+  "$PYTHON_BIN" tools/merge_predictor_prefeature_manifests.py \
+    --dataset_root "$VAL_ROOT" --expected_cases 25 --expected_actions 4 --expected_chunks 8
+fi
+
+extract() {
+  local split="$1" manifest="$2" output="$FEATURE_ROOT/$1"
+  mkdir -p "$output"
+  if [[ "$(find "$output" -maxdepth 1 -name 'features_rank_*.pt' | wc -l)" -ne "$NPROC" ]]; then
+    rm -f "$output"/features_rank_*.pt
+    CUDA_VISIBLE_DEVICES="$GPU_IDS" "$PYTHON_BIN" -m torch.distributed.run \
+      --standalone --nproc_per_node="$NPROC" tools/extract_predictor_confidence_features.py \
+      --manifest "$manifest" --predictor_checkpoint "$PREDICTOR" \
+      --teacher_checkpoint "$TEACHER" --output_dir "$output" --batch_size 8
+  fi
+}
+
+extract train "$TRAIN_ROOT/train_eval_manifest.jsonl"
+extract validation "$VAL_ROOT/train_eval_manifest.jsonl"
+CUDA_VISIBLE_DEVICES="$GPU_IDS" "$PYTHON_BIN" -m torch.distributed.run \
+  --standalone --nproc_per_node="$NPROC" tools/train_evaluate_predictor_confidence.py \
+  --train_features "$FEATURE_ROOT/train" --validation_features "$FEATURE_ROOT/validation" \
+  --output_dir "$OUTPUT_ROOT" --epochs 40 --batch_size 256 --seed 0

tools/run_predictor_v4_atc_full_experiment.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+max_steps="${ATC_MAX_STEPS:-2000}"
+variants=(full anchor_only raw_prev no_gate no_distance)
+
+for variant in "${variants[@]}"; do
+  bash "${repo_root}/tools/launch_predictor_v4_atc_stage1_8gpu.sh" \
+    "${variant}" "${max_steps}"
+done
+
+for variant in "${variants[@]}"; do
+  checkpoint_dir="${repo_root}/checkpoints/predictor_v4_atc-${variant}_blocks1-52_fulltrain100_fp32master_8gpu_flr1e-4_blr1e-5_steps${max_steps}"
+  weights="${checkpoint_dir}/predictor_step_$(printf '%05d' "${max_steps}").safetensors"
+  for schedule in fppf fppp; do
+    replace_steps="1,2"
+    [[ "${schedule}" == "fppp" ]] && replace_steps="1,2,3"
+    eval_name="eval_validation25_atc-${variant}_schedule-${schedule}_blocks1-52_step${max_steps}_oldenv"
+    bash "${repo_root}/tools/launch_vbench_validation_predictor.sh" \
+      "${eval_name}" "${weights}" 1,52 v4 "${replace_steps}" \
+      same_step concat atc "${variant}"
+  done
+done

tools/run_predictor_v4_atc_global_sequential_8gpu.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Train the global-transport ATC variants one after another on 8 GPUs:
+# per-rank batch 8, no gradient accumulation (global batch 64), 2000 steps each.
+set -euo pipefail
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+max_steps="${ATC_MAX_STEPS:-2000}"
+scopes=("${@:-}")
+[[ -n "${scopes[0]}" ]] || scopes=(chunk last_frame)
+for scope in "${scopes[@]}"; do
+  echo "[$(date -Is)] start scope=${scope}"
+  PREDICTOR_RDZV_PORT=29501 bash "${repo_root}/tools/launch_predictor_v4_atc_global_stage1.sh" \
+    "${scope}" 0,1,2,3,4,5,6,7 8 1 "${max_steps}"
+  echo "[$(date -Is)] done scope=${scope}"
+done

tools/run_predictor_v4_detached_timestep_rollout_offline_targets_overfit8.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+config_tag="flr1e-4_blr1e-5_schedsteps1000_swarmup8_bwarmup8"
+run_name="detached-timestep-rollout-offline-ffff-targets_blocks1-52_overfit8_seed20260721_fp32master_8gpu_${config_tag}"
+checkpoint_dir="${repo_root}/checkpoints/predictor_v4_${run_name}"
+eval_prefix="detached-timestep-rollout-offline-ffff-targets-overfit8"
+summary_name="summary_${eval_prefix}_ckptstep1000_${config_tag}"
+summary_root="/mnt/local_nvme/zoubin/cz/hyworldplay_${summary_name}"
+final_weights="${checkpoint_dir}/predictor_step_01000.safetensors"
+mkdir -p "${checkpoint_dir}" "${summary_root}"
+
+export BUCKET="${BUCKET:-s3-us-west2-default}"
+export FS_ID="${FS_ID:-fs-05c60be7352499179}"
+export MOUNT_POINT="${MOUNT_POINT:-/mnt/s3files/s3-us-west2-default}"
+export PYTHONPATH="${repo_root}"
+
+exec 9>"${summary_root}/pipeline.lock"
+if ! flock -n 9; then
+  echo "[pipeline] detached offline-target rollout pipeline is already active"
+  exit 0
+fi
+
+run_with_retries() {
+  local stage="$1"
+  shift
+  local attempt=1
+  while true; do
+    echo "[pipeline] stage=${stage} attempt=${attempt} start=$(date -u +%FT%TZ)"
+    if "$@"; then
+      echo "[pipeline] stage=${stage} complete=$(date -u +%FT%TZ)"
+      return 0
+    fi
+    if [[ "${attempt}" -ge 5 ]]; then
+      echo "[pipeline] stage=${stage} failed after ${attempt} attempts" >&2
+      return 1
+    fi
+    attempt=$((attempt + 1))
+    sleep 30
+  done
+}
+
+train_model() {
+  if [[ -f "${final_weights}" ]]; then
+    echo "[pipeline] step 1000 already exists"
+    return 0
+  fi
+  local resume_path=""
+  if [[ -f "${checkpoint_dir}/training_latest.pt" ]]; then
+    resume_path="${checkpoint_dir}/training_latest.pt"
+  fi
+  bash "${repo_root}/tools/launch_predictor_v4_detached_timestep_rollout_offline_targets_overfit8_training.sh" \
+    "${checkpoint_dir}" "predictor-v4-${run_name//_/-}" "${resume_path}" 1000
+  [[ -f "${final_weights}" ]]
+}
+
+evaluate_model() {
+  local schedule="$1"
+  local replace_steps="$2"
+  local eval_root="/mnt/local_nvme/zoubin/cz/hyworldplay_eval_v4_${eval_prefix}_schedule-${schedule}_blocks1-52_ckptstep1000_${config_tag}"
+  local durable_name="eval_${eval_prefix}_schedule-${schedule}_blocks1-52_ckptstep1000_${config_tag}"
+  if [[ -f "${eval_root}/metrics.completed" && -f "${eval_root}/sync.completed" ]]; then
+    echo "[pipeline] ${schedule} step-1000 evaluation already complete"
+    return 0
+  fi
+  bash "${repo_root}/tools/launch_predictor_v4_rollout_overfit8_eval.sh" \
+    "${eval_root}" "${final_weights}" "${durable_name}" "${replace_steps}"
+  [[ -f "${eval_root}/metrics.json" && -f "${eval_root}/sync.completed" ]]
+}
+
+compare_to() {
+  local baseline_label="$1"
+  local baseline_fppf="$2"
+  local baseline_fppp="$3"
+  local output_name="$4"
+  local candidate_prefix="/mnt/local_nvme/zoubin/cz/hyworldplay_eval_v4_${eval_prefix}"
+  "${python_bin}" "${repo_root}/tools/compare_predictor_overfit8_metrics.py" \
+    --baseline_label "${baseline_label}" \
+    --baseline_fppf "${baseline_fppf}" \
+    --baseline_fppp "${baseline_fppp}" \
+    --candidate_label "detached-timestep-rollout-offline-ffff-targets-step1000" \
+    --candidate_fppf "${candidate_prefix}_schedule-fppf_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+    --candidate_fppp "${candidate_prefix}_schedule-fppp_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+    --output "${summary_root}/${output_name}.json" \
+    >"${summary_root}/${output_name}.log" 2>&1
+}
+
+run_with_retries dataset \
+  bash "${repo_root}/tools/ensure_predictor_prefeature_nvme.sh"
+run_with_retries train_step1000 train_model
+run_with_retries eval_step1000_fppf evaluate_model fppf "1,2"
+run_with_retries eval_step1000_fppp evaluate_model fppp "1,2,3"
+
+run_with_retries compare_stage1 compare_to \
+  "stage1-step2000" \
+  "${repo_root}/outputs/predictor_v4/eval_stage1_overfit8_schedule-fppf_blocks1-52_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100/metrics.json" \
+  "${repo_root}/outputs/predictor_v4/eval_stage1_overfit8_schedule-fppp_blocks1-52_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100/metrics.json" \
+  comparison_vs_stage1
+run_with_retries compare_grouped_offline compare_to \
+  "grouped-teacher-forcing-offline-prefeature-step1000" \
+  "${repo_root}/outputs/predictor_v4/eval_grouped-teacher-forcing-offline-prefeature-overfit8_schedule-fppf_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+  "${repo_root}/outputs/predictor_v4/eval_grouped-teacher-forcing-offline-prefeature-overfit8_schedule-fppp_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+  comparison_vs_grouped_offline
+run_with_retries compare_detached_online compare_to \
+  "detached-timestep-only-online-same-state-step1000" \
+  "${repo_root}/outputs/predictor_v4/eval_timestep-rollout-detached-timestepfp32-overfit8-pure_schedule-fppf_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+  "${repo_root}/outputs/predictor_v4/eval_timestep-rollout-detached-timestepfp32-overfit8-pure_schedule-fppp_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+  comparison_vs_detached_online_same_state
+
+date -u +%FT%TZ >"${summary_root}/pipeline.completed"
+aws s3 sync "${summary_root}" \
+  "s3://${BUCKET}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/outputs/predictor_v4/${summary_name}" \
+  --only-show-errors
+echo "[pipeline] training, final evaluations, and three comparisons complete"

tools/run_predictor_v4_grouped_teacher_forcing_overfit8.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+config_tag="flr1e-4_blr1e-5_schedsteps1000_swarmup8_bwarmup8"
+run_name="grouped-teacher-forcing-offline-prefeature_blocks1-52_overfit8_seed20260721_fp32master_8gpu_${config_tag}"
+checkpoint_dir="${repo_root}/checkpoints/predictor_v4_${run_name}"
+eval_prefix="grouped-teacher-forcing-offline-prefeature-overfit8"
+summary_name="summary_grouped-teacher-forcing-offline-prefeature-vs-detached-timestepfp32-overfit8_ckptstep1000_${config_tag}"
+summary_root="/mnt/local_nvme/zoubin/cz/hyworldplay_${summary_name}"
+final_weights="${checkpoint_dir}/predictor_step_01000.safetensors"
+mkdir -p "${checkpoint_dir}" "${summary_root}"
+
+export BUCKET="${BUCKET:-s3-us-west2-default}"
+export FS_ID="${FS_ID:-fs-05c60be7352499179}"
+export MOUNT_POINT="${MOUNT_POINT:-/mnt/s3files/s3-us-west2-default}"
+export PYTHONPATH="${repo_root}"
+
+exec 9>"${summary_root}/pipeline.lock"
+if ! flock -n 9; then
+  echo "[pipeline] grouped teacher-forcing pipeline is already active"
+  exit 0
+fi
+
+run_with_retries() {
+  local stage="$1"
+  shift
+  local attempt=1
+  while true; do
+    echo "[pipeline] stage=${stage} attempt=${attempt} start=$(date -u +%FT%TZ)"
+    if "$@"; then
+      echo "[pipeline] stage=${stage} complete=$(date -u +%FT%TZ)"
+      return 0
+    fi
+    if [[ "${attempt}" -ge 5 ]]; then
+      echo "[pipeline] stage=${stage} failed after ${attempt} attempts" >&2
+      return 1
+    fi
+    attempt=$((attempt + 1))
+    sleep 30
+  done
+}
+
+train_grouped() {
+  if [[ -f "${final_weights}" ]]; then
+    echo "[pipeline] grouped teacher-forcing step 1000 already exists"
+    return 0
+  fi
+  local resume_path=""
+  if [[ -f "${checkpoint_dir}/training_latest.pt" ]]; then
+    resume_path="${checkpoint_dir}/training_latest.pt"
+  fi
+  bash "${repo_root}/tools/launch_predictor_v4_grouped_teacher_forcing_overfit8_training.sh" \
+    "${checkpoint_dir}" \
+    "predictor-v4-${run_name//_/-}" \
+    "${resume_path}" 1000
+  [[ -f "${final_weights}" ]]
+}
+
+evaluate_grouped() {
+  local schedule="$1"
+  local replace_steps="$2"
+  local eval_root="/mnt/local_nvme/zoubin/cz/hyworldplay_eval_v4_${eval_prefix}_schedule-${schedule}_blocks1-52_ckptstep1000_${config_tag}"
+  local durable_name="eval_${eval_prefix}_schedule-${schedule}_blocks1-52_ckptstep1000_${config_tag}"
+  if [[ -f "${eval_root}/metrics.completed" && -f "${eval_root}/sync.completed" ]]; then
+    echo "[pipeline] ${schedule} step-1000 evaluation already complete"
+    return 0
+  fi
+  bash "${repo_root}/tools/launch_predictor_v4_rollout_overfit8_eval.sh" \
+    "${eval_root}" "${final_weights}" "${durable_name}" "${replace_steps}"
+  [[ -f "${eval_root}/metrics.json" && -f "${eval_root}/sync.completed" ]]
+}
+
+run_with_retries dataset \
+  bash "${repo_root}/tools/ensure_predictor_prefeature_nvme.sh"
+run_with_retries train_step1000 train_grouped
+
+# Only the final step-1000 checkpoint is evaluated.
+run_with_retries eval_step1000_fppf evaluate_grouped fppf "1,2"
+run_with_retries eval_step1000_fppp evaluate_grouped fppp "1,2,3"
+
+baseline_prefix="${repo_root}/outputs/predictor_v4/eval_timestep-rollout-detached-timestepfp32-overfit8-pure"
+baseline_suffix="blocks1-52_ckptstep1000_${config_tag}/metrics.json"
+candidate_prefix="/mnt/local_nvme/zoubin/cz/hyworldplay_eval_v4_${eval_prefix}"
+"${python_bin}" "${repo_root}/tools/compare_predictor_overfit8_metrics.py" \
+  --baseline_label "detached-timestep-only-step1000" \
+  --baseline_fppf "${baseline_prefix}_schedule-fppf_${baseline_suffix}" \
+  --baseline_fppp "${baseline_prefix}_schedule-fppp_${baseline_suffix}" \
+  --candidate_label "grouped-teacher-forcing-offline-prefeature-step1000" \
+  --candidate_fppf "${candidate_prefix}_schedule-fppf_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+  --candidate_fppp "${candidate_prefix}_schedule-fppp_blocks1-52_ckptstep1000_${config_tag}/metrics.json" \
+  --output "${summary_root}/comparison.json" \
+  >"${summary_root}/comparison.log" 2>&1
+date -u +%FT%TZ >"${summary_root}/pipeline.completed"
+aws s3 sync "${summary_root}" \
+  "s3://${BUCKET}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/outputs/predictor_v4/${summary_name}" \
+  --only-show-errors
+echo "[pipeline] grouped teacher forcing, final evaluations, and comparison complete"

tools/run_predictor_v4_timestep_rollout_detached_overfit8_experiments.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+export TIMESTEP_ROLLOUT_SUITE_NAME="timestep_rollout_detached_timestepfp32_blocks1-52_overfit8_seed20260721_fp32master_8gpu"
+export TIMESTEP_ROLLOUT_EVAL_SUITE_NAME="timestep-rollout-detached-timestepfp32-overfit8"
+export TIMESTEP_ROLLOUT_DETACH_BETWEEN_TIMESTEPS="true"
+export TIMESTEP_ROLLOUT_VARIANTS="pure:0.0"
+export TIMESTEP_ROLLOUT_MAX_STEPS="1000"
+
+exec bash "${repo_root}/tools/run_predictor_v4_timestep_rollout_overfit8_experiments.sh"

tools/run_predictor_v4_timestep_rollout_overfit8_experiments.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+suite_name="${TIMESTEP_ROLLOUT_SUITE_NAME:-timestep_rollout_timestepfp32_blocks1-52_overfit8_seed20260721_fp32master_8gpu}"
+eval_suite_name="${TIMESTEP_ROLLOUT_EVAL_SUITE_NAME:-timestep-rollout-timestepfp32-overfit8}"
+detach_between_timesteps="${TIMESTEP_ROLLOUT_DETACH_BETWEEN_TIMESTEPS:-false}"
+variant_specs="${TIMESTEP_ROLLOUT_VARIANTS:-replay0:0.0 replay0p2:0.2 replay0p4:0.4}"
+max_steps="${TIMESTEP_ROLLOUT_MAX_STEPS:-200}"
+stop_after_steps="${TIMESTEP_ROLLOUT_STOP_AFTER_STEPS:-${max_steps}}"
+checkpoint_parent="${repo_root}/checkpoints/predictor_v4_${suite_name}"
+config_tag="flr1e-4_blr1e-5_schedsteps${max_steps}_swarmup8_bwarmup8"
+checkpoint_parent="${checkpoint_parent}_${config_tag}"
+eval_parent="/mnt/local_nvme/zoubin/cz/hyworldplay_eval_v4_${eval_suite_name}_blocks1-52_ckptstep${stop_after_steps}_${config_tag}"
+pipeline_root="/mnt/local_nvme/zoubin/cz/hyworldplay_summary_v4_${eval_suite_name}_ckptstep${stop_after_steps}_${config_tag}"
+mkdir -p "${checkpoint_parent}" "${eval_parent}" "${pipeline_root}"
+
+export BUCKET="${BUCKET:-s3-us-west2-default}"
+export FS_ID="${FS_ID:-fs-05c60be7352499179}"
+export MOUNT_POINT="${MOUNT_POINT:-/mnt/s3files/s3-us-west2-default}"
+export PYTHONPATH="${repo_root}"
+
+exec 9>"${pipeline_root}/pipeline.lock"
+if ! flock -n 9; then
+  echo "[pipeline] another timestep-rollout sweep is already active"
+  exit 0
+fi
+
+run_with_retries() {
+  local stage="$1"
+  shift
+  local attempt=1
+  while true; do
+    echo "[pipeline] stage=${stage} attempt=${attempt} start=$(date -u +%FT%TZ)"
+    if "$@"; then
+      echo "[pipeline] stage=${stage} complete=$(date -u +%FT%TZ)"
+      return 0
+    fi
+    if [[ "${attempt}" -ge 5 ]]; then
+      echo "[pipeline] stage=${stage} failed after ${attempt} attempts" >&2
+      return 1
+    fi
+    attempt=$((attempt + 1))
+    sleep 30
+  done
+}
+
+train_variant() {
+  local label="$1"
+  local replay_weight="$2"
+  local output_dir="${checkpoint_parent}/${label}"
+  local final_step
+  printf -v final_step "%05d" "${stop_after_steps}"
+  local final_weights="${output_dir}/predictor_step_${final_step}.safetensors"
+  if [[ -f "${final_weights}" ]]; then
+    echo "[pipeline] training ${label} already complete"
+    return 0
+  fi
+  local resume_path=""
+  if [[ -f "${output_dir}/training_latest.pt" ]]; then
+    resume_path="${output_dir}/training_latest.pt"
+  fi
+  bash "${repo_root}/tools/launch_predictor_v4_timestep_rollout_overfit8_training.sh" \
+    "${output_dir}" "${replay_weight}" \
+    "predictor-v4-${suite_name}-${label}-${config_tag//_/-}" \
+    "${resume_path}" "${detach_between_timesteps}" "${max_steps}" \
+    "${stop_after_steps}"
+  [[ -f "${final_weights}" ]]
+}
+
+evaluate_variant() {
+  local label="$1"
+  local schedule="$2"
+  local replace_steps="$3"
+  local final_step
+  printf -v final_step "%05d" "${stop_after_steps}"
+  local weights="${checkpoint_parent}/${label}/predictor_step_${final_step}.safetensors"
+  local eval_root="${eval_parent}/${label}_${schedule}"
+  local durable_name="eval_${eval_suite_name}_${label}_schedule-${schedule}_blocks1-52_ckptstep${stop_after_steps}_${config_tag}"
+  if [[ -f "${eval_root}/metrics.completed" && -f "${eval_root}/sync.completed" ]]; then
+    echo "[pipeline] evaluation ${label}/${schedule} already complete"
+    return 0
+  fi
+  bash "${repo_root}/tools/launch_predictor_v4_rollout_overfit8_eval.sh" \
+    "${eval_root}" "${weights}" "${durable_name}" "${replace_steps}"
+  [[ -f "${eval_root}/metrics.json" && -f "${eval_root}/sync.completed" ]]
+}
+
+run_with_retries sidecar \
+  bash "${repo_root}/tools/ensure_predictor_timestep_rollout_overfit8_sidecar.sh"
+
+for spec in ${variant_specs}; do
+  label="${spec%%:*}"
+  replay_weight="${spec##*:}"
+  run_with_retries "train_${label}" train_variant "${label}" "${replay_weight}"
+done
+
+for spec in ${variant_specs}; do
+  label="${spec%%:*}"
+  run_with_retries "eval_${label}_fppp" evaluate_variant "${label}" fppp "1,2,3"
+  run_with_retries "eval_${label}_fppf" evaluate_variant "${label}" fppf "1,2"
+done
+
+summary_path="${pipeline_root}/summary.json"
+"${python_bin}" "${repo_root}/tools/summarize_predictor_timestep_rollout_overfit8.py" \
+  --eval_parent "${eval_parent}" --output "${summary_path}" \
+  --experiment "v4 ${suite_name}; scheduler_max_steps=${max_steps}; stop_after_steps=${stop_after_steps}; detach_between_timesteps=${detach_between_timesteps}" \
+  --variants "${variant_specs}" \
+  >"${pipeline_root}/summary.log" 2>&1
+date -u +%FT%TZ >"${pipeline_root}/pipeline.completed"
+aws s3 sync "${pipeline_root}" \
+  "s3://${BUCKET}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/outputs/predictor_v4/summary_${eval_suite_name}_ckptstep${stop_after_steps}_${config_tag}" \
+  --only-show-errors
+echo "[pipeline] all training and evaluation stages complete"

tools/run_predictor_v4_validation5_rollout_comparison.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/${dataset_name}}"
+validation_root="${dataset_root}/validation"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+case_ids="0,8,15,19,21"
+subset_tag="validation5_seed20260722_cases0-8-15-19-21"
+config_tag="flr1e-4_blr1e-5_schedsteps1000_swarmup8_bwarmup8"
+summary_root="${dataset_root}/evaluations/summary_${subset_tag}_three-stage2-variants"
+pipeline_log_dir="${summary_root}/logs"
+mkdir -p "${pipeline_log_dir}"
+
+export BUCKET="${BUCKET:-s3-us-west2-default}"
+export FS_ID="${FS_ID:-fs-05c60be7352499179}"
+export MOUNT_POINT="${MOUNT_POINT:-/mnt/s3files/s3-us-west2-default}"
+export PYTHONPATH="${repo_root}"
+export HY_PROFILE_TIMING=1
+
+durable_dataset_uri="s3://${BUCKET}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}"
+durable_eval_uri="${durable_dataset_uri}/evaluations"
+
+exec 9>"${summary_root}/pipeline.lock"
+if ! flock -n 9; then
+  echo "[pipeline] validation5 comparison is already active"
+  exit 0
+fi
+
+if [[ ! -f "${validation_root}/cases.jsonl" ]] \
+  || [[ $(find "${validation_root}/input_images" -type f -name '*.jpg' 2>/dev/null | wc -l) -ne 25 ]] \
+  || [[ $(find "${validation_root}/full" -type f -name '*.mp4' 2>/dev/null | wc -l) -ne 100 ]]; then
+  echo "[dataset] restoring validation cache from ${durable_dataset_uri}"
+  mkdir -p "${dataset_root}"
+  aws s3 sync "${durable_dataset_uri}" "${dataset_root}" --only-show-errors
+fi
+
+[[ -f "${validation_root}/cases.jsonl" ]]
+[[ $(find "${validation_root}/input_images" -type f -name '*.jpg' | wc -l) -eq 25 ]]
+[[ $(find "${validation_root}/full" -type f -name '*.mp4' | wc -l) -eq 100 ]]
+cp "${repo_root}/configs/validation5_seed20260722.json" "${summary_root}/selection.json"
+
+declare -a variants=(
+  "online-same-state|${repo_root}/checkpoints/predictor_v4_timestep_rollout_detached_timestepfp32_blocks1-52_overfit8_seed20260721_fp32master_8gpu_${config_tag}/pure/predictor_step_01000.safetensors"
+  "grouped-offline-teacher-forcing|${repo_root}/checkpoints/predictor_v4_grouped-teacher-forcing-offline-prefeature_blocks1-52_overfit8_seed20260721_fp32master_8gpu_${config_tag}/predictor_step_01000.safetensors"
+  "offline-ffff-target-rollout|${repo_root}/checkpoints/predictor_v4_detached-timestep-rollout-offline-ffff-targets_blocks1-52_overfit8_seed20260721_fp32master_8gpu_${config_tag}/predictor_step_01000.safetensors"
+)
+
+run_workers() {
+  local log_dir="$1"
+  local phase="$2"
+  shift 2
+  local pids=()
+  local worker_id worker_pid failed=0
+  mkdir -p "${log_dir}"
+  for worker_id in $(seq 0 7); do
+    CUDA_VISIBLE_DEVICES="${worker_id}" \
+      "${python_bin}" -u "$@" \
+        --worker_id "${worker_id}" --num_workers 8 \
+        >"${log_dir}/${phase}_worker_${worker_id}.log" 2>&1 &
+    worker_pid=$!
+    pids+=("${worker_pid}")
+    echo "${worker_pid}" >"${log_dir}/${phase}_worker_${worker_id}.pid"
+  done
+  for worker_pid in "${pids[@]}"; do
+    if ! wait "${worker_pid}"; then
+      failed=1
+    fi
+  done
+  if [[ "${failed}" -ne 0 ]]; then
+    echo "${phase} worker failure; inspect ${log_dir}/${phase}_worker_*.log" >&2
+    return 1
+  fi
+}
+
+run_with_retries() {
+  local stage="$1"
+  shift
+  local attempt=1
+  while true; do
+    echo "[pipeline] stage=${stage} attempt=${attempt} start=$(date -u +%FT%TZ)"
+    if "$@"; then
+      echo "[pipeline] stage=${stage} complete=$(date -u +%FT%TZ)"
+      return 0
+    fi
+    if [[ "${attempt}" -ge 5 ]]; then
+      echo "[pipeline] stage=${stage} failed after ${attempt} attempts" >&2
+      return 1
+    fi
+    attempt=$((attempt + 1))
+    sleep 30
+  done
+}
+
+evaluate_one() {
+  local variant="$1"
+  local weights="$2"
+  local schedule="$3"
+  local replace_steps="$4"
+  local eval_name="eval_${subset_tag}_${variant}_schedule-${schedule}_blocks1-52_ckptstep1000_${config_tag}"
+  local eval_root="${dataset_root}/evaluations/${eval_name}"
+  local log_dir="${eval_root}/logs"
+  mkdir -p "${log_dir}"
+  [[ -f "${weights}" ]]
+
+  local video_count=0
+  if [[ -d "${eval_root}/predictor" ]]; then
+    video_count=$(find "${eval_root}/predictor" -type f -name '*.mp4' | wc -l)
+  fi
+  if [[ ! -f "${eval_root}/generation.completed" || "${video_count}" -ne 20 ]]; then
+    date -u +%FT%TZ >"${eval_root}/generation.started"
+    run_workers "${log_dir}" generation \
+      "${repo_root}/tools/generate_predictor_v4_train_case_eval.py" \
+      --dataset_root "${validation_root}" \
+      --output_root "${eval_root}" \
+      --weights "${weights}" \
+      --source_blocks 1,52 \
+      --predictor_variant v4 \
+      --case_ids "${case_ids}" \
+      --modes predictor \
+      --replace_steps "${replace_steps}"
+    [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' | wc -l) -eq 20 ]]
+    date -u +%FT%TZ >"${eval_root}/generation.completed"
+  else
+    echo "[skip] generation complete: ${eval_name}"
+  fi
+
+  local metric_records=0
+  if [[ -f "${eval_root}/metrics.json" ]]; then
+    metric_records=$("${python_bin}" -c \
+      'import json,sys; print(len(json.load(open(sys.argv[1]))["records"]))' \
+      "${eval_root}/metrics.json")
+  fi
+  if [[ ! -f "${eval_root}/metrics.completed" || "${metric_records}" -ne 20 ]]; then
+    date -u +%FT%TZ >"${eval_root}/metrics.started"
+    run_workers "${log_dir}" metrics \
+      "${repo_root}/tools/compute_predictor_v4_train_case_metrics.py" \
+      --dataset_root "${validation_root}" \
+      --output_root "${eval_root}" \
+      --num_cases 25 \
+      --case_ids "${case_ids}" \
+      --reference_subdir full \
+      --modes predictor \
+      --metric_batch_size 4
+    "${python_bin}" "${repo_root}/tools/merge_predictor_v4_train_case_metrics.py" \
+      --output_root "${eval_root}" \
+      --num_workers 8 \
+      --num_cases 5 \
+      --modes predictor \
+      --replace_steps "${replace_steps}" \
+      --reference_label "Full-DiT validation videos; ${subset_tag}" \
+      >"${log_dir}/metrics_merge.log" 2>&1
+    [[ $("${python_bin}" -c \
+      'import json,sys; print(len(json.load(open(sys.argv[1]))["records"]))' \
+      "${eval_root}/metrics.json") -eq 20 ]]
+    date -u +%FT%TZ >"${eval_root}/metrics.completed"
+  else
+    echo "[skip] metrics complete: ${eval_name}"
+  fi
+
+  aws s3 sync "${eval_root}" "${durable_eval_uri}/${eval_name}" --only-show-errors
+  date -u +%FT%TZ >"${eval_root}/sync.completed"
+  aws s3 cp "${eval_root}/sync.completed" \
+    "${durable_eval_uri}/${eval_name}/sync.completed" --only-show-errors
+}
+
+for spec in "${variants[@]}"; do
+  IFS='|' read -r variant weights <<<"${spec}"
+  run_with_retries "${variant}_fppf" evaluate_one "${variant}" "${weights}" fppf "1,2"
+  run_with_retries "${variant}_fppp" evaluate_one "${variant}" "${weights}" fppp "1,2,3"
+done
+
+date -u +%FT%TZ >"${summary_root}/pipeline.completed"
+aws s3 sync "${summary_root}" "${durable_eval_uri}/$(basename "${summary_root}")" --only-show-errors
+echo "[pipeline] all validation5 evaluations completed"

tools/run_stage1_continued_validation25_evaluation.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+vbench_repo="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/VBench"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/${dataset_name}}"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+weights="${repo_root}/checkpoints/predictor_v4_prefeature-continued-from-stage1step2000_blocks1-52_fulltrain100_fp32master_8gpu_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs16_swanlab/predictor_step_02000.safetensors"
+eval_prefix="eval_validation25_stage1-continued-offline-tf"
+eval_suffix="blocks1-52_ckptstep2000-initstage1step2000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs16"
+fppf_name="${eval_prefix}_schedule-fppf_${eval_suffix}"
+fppp_name="${eval_prefix}_schedule-fppp_${eval_suffix}"
+run_name="validation25_stage1_continued_offline_tf_step2000"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/${run_name}"
+
+export PYTHONPATH="${repo_root}"
+
+bash "${repo_root}/tools/launch_vbench_validation_predictor.sh" \
+  "${fppf_name}" "${weights}" "1,52" v4 "1,2"
+bash "${repo_root}/tools/launch_vbench_validation_predictor.sh" \
+  "${fppp_name}" "${weights}" "1,52" v4 "1,2,3"
+
+export PYTHONPATH="${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/vbench"
+export TORCH_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/torch"
+export HF_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/huggingface"
+
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+group_fppf="stage1_continued_offline_tf_fppf"
+group_fppp="stage1_continued_offline_tf_fppp"
+declare -a groups=(
+  "${group_fppf}|${dataset_root}/evaluations/${fppf_name}/predictor"
+  "${group_fppp}|${dataset_root}/evaluations/${fppp_name}/predictor"
+)
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  video_count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  if [[ "${video_count}" -ne 100 ]]; then
+    echo "${label}: expected 100 videos, found ${video_count}: ${source_dir}" >&2
+    exit 1
+  fi
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+
+staged_count=$(find "${staging_root}" -maxdepth 1 -type l | wc -l)
+if [[ "${staged_count}" -ne 200 ]]; then
+  echo "Expected 200 staged videos, found ${staged_count}" >&2
+  exit 1
+fi
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count 200
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json
+import sys
+
+path, dimension = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == 200, (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  --group "${group_fppf}" \
+  --group "${group_fppp}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+echo "[validation] all standard and VBench metrics complete: ${run_root}"

tools/run_stage1_previous_condition_ablation.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=/mnt/local_nvme/cz/projects/HY-WorldPlay-DEV-Predictor
+predictor_env=/mnt/local_nvme/cz/envs/hy_worldplay_july20260720
+python_bin="$predictor_env/bin/python"
+manifest="$repo_root/datasets/hyworldplay_predictor_prefeature_v4/train_eval_manifest.jsonl"
+teacher=/mnt/local_nvme/cz/checkpoints/hy_worldplay/huggingface/hub/models--tencent--HY-WorldPlay/snapshots/f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/diffusion_pytorch_model.safetensors
+suite_root="$repo_root/checkpoints/predictor_v4_stage1_previous_condition_ablation_seed0"
+log_root="$repo_root/logs/predictor_v4_stage1_previous_condition_ablation_seed0"
+s3_root=s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor
+modes=(none previous_step both)
+
+export PATH="$predictor_env/bin:$PATH"
+export PYTHONPATH="$repo_root"
+export OMP_NUM_THREADS=4
+export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+export TORCH_NCCL_ASYNC_ERROR_HANDLING=1
+export SSL_CERT_FILE="$predictor_env/lib/python3.10/site-packages/certifi/cacert.pem"
+export REQUESTS_CA_BUNDLE="$SSL_CERT_FILE"
+
+mkdir -p "$suite_root" "$log_root"
+
+"$python_bin" - <<'PY' | tee "$log_root/environment.log"
+import importlib.util
+import torch
+
+assert torch.__version__ == "2.6.0+cu124", torch.__version__
+assert torch.version.cuda == "12.4", torch.version.cuda
+assert importlib.util.find_spec("flash_attn") is None, "flash_attn must not be installed"
+print(f"torch={torch.__version__} cuda={torch.version.cuda} flash_attn=False")
+PY
+
+for mode in "${modes[@]}"; do
+  output_dir="$suite_root/$mode"
+  log_file="$log_root/${mode}.log"
+  complete_marker="$output_dir/training.complete"
+  if [[ -f "$complete_marker" && -f "$output_dir/predictor_step_02000.safetensors" ]]; then
+    echo "[skip] $mode already complete"
+    continue
+  fi
+  mkdir -p "$output_dir"
+  resume_args=()
+  if [[ -f "$output_dir/training_latest.pt" ]]; then
+    resume_args+=(--resume "$output_dir/training_latest.pt")
+  fi
+  echo "[start] mode=$mode $(date -u +%FT%TZ)" | tee -a "$log_file"
+  "$python_bin" -m torch.distributed.run \
+    --standalone --nproc_per_node=8 \
+    "$repo_root/train_predictor_v4.py" \
+    --manifest "$manifest" \
+    --teacher_checkpoint "$teacher" \
+    --source_blocks 1,52 \
+    --previous_condition_mode "$mode" \
+    --output_dir "$output_dir" \
+    --batch_size 16 \
+    --gradient_accumulation_steps 1 \
+    --max_steps 2000 \
+    --seed 0 \
+    --fusion_lr 1e-4 \
+    --blocks_lr 1e-5 \
+    --scheduler_warmup_steps 100 \
+    --block_warmup_steps 100 \
+    --block_warmup_mode delayed \
+    --fp32_trainable_params \
+    --gradient_checkpointing \
+    --bucket_by_context \
+    --save_every 100 \
+    --keep_snapshots 20 \
+    --log_every 10 \
+    --swanlab_mode cloud \
+    --swanlab_experiment "predictor-v4-stage1-previous-${mode}-seed0-blocks1-52-fp32master-8gpu-torch26-noflash" \
+    "${resume_args[@]}" \
+    2>&1 | tee -a "$log_file"
+  test -f "$output_dir/predictor_step_02000.safetensors"
+  date -u +%FT%TZ >"$complete_marker"
+  aws s3 sync "$output_dir" "$s3_root/checkpoints/predictor_v4_stage1_previous_condition_ablation_seed0/$mode" --only-show-errors
+  aws s3 sync "$log_root" "$s3_root/logs/predictor_v4_stage1_previous_condition_ablation_seed0" --only-show-errors
+  echo "[complete] mode=$mode $(date -u +%FT%TZ)" | tee -a "$log_file"
+done
+
+date -u +%FT%TZ >"$suite_root/suite.complete"
+aws s3 cp "$suite_root/suite.complete" "$s3_root/checkpoints/predictor_v4_stage1_previous_condition_ablation_seed0/suite.complete" --only-show-errors
+echo "[complete] all modes $(date -u +%FT%TZ)"

tools/run_stage1_previous_condition_retrain_validation.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+repo_root=/mnt/local_nvme/cz/projects/HY-WorldPlay-DEV-Predictor
+predictor_env=/mnt/local_nvme/cz/envs/hy_worldplay_july20260720
+python_bin="$predictor_env/bin/python"
+base_model="$repo_root/outputs/hf_snapshot_repaired_9b49404"
+checkpoint_root="$repo_root/checkpoints/predictor_v4_stage1_previous_condition_ablation_seed0"
+run_tag=torch26-retrain_20260824
+run_root="$repo_root/logs/stage1_previous_condition_validation_${run_tag}"
+status_file="$run_root/status.tsv"
+
+export PATH="$predictor_env/bin:$PATH"
+export PYTHONPATH="$repo_root"
+export PREDICTOR_PYTHON_BIN="$python_bin"
+export PREDICTOR_BASE_MODEL="$base_model"
+export PREDICTOR_SKIP_SYNC=0
+
+mkdir -p "$run_root"
+exec > >(tee -a "$run_root/sequential.log") 2>&1
+
+record_status() {
+  printf '%s\t%s\t%s\n' "$1" "$(date -u +%FT%TZ)" "$2" >>"$status_file"
+}
+
+on_error() {
+  local exit_code="$?"
+  record_status failed "line=${BASH_LINENO[0]} exit=${exit_code}"
+  exit "$exit_code"
+}
+trap on_error ERR
+
+"$python_bin" - <<'PY'
+import importlib.util
+import torch
+
+assert torch.__version__ == "2.6.0+cu124", torch.__version__
+assert torch.version.cuda == "12.4", torch.version.cuda
+assert importlib.util.find_spec("flash_attn") is None, "flash_attn must not be installed"
+print(f"torch={torch.__version__} cuda={torch.version.cuda} flash_attn=False")
+PY
+test -d "$base_model"
+record_status preflight "torch=2.6.0+cu124 cuda=12.4 flash_attn=False"
+
+run_eval() {
+  local label="$1"
+  local mode="$2"
+  local checkpoint="$checkpoint_root/$mode/predictor_step_02000.safetensors"
+  local eval_name="eval_validation25_previous-condition-${label}_${run_tag}"
+  test -f "$checkpoint"
+  record_status start "$eval_name"
+  bash "$repo_root/tools/launch_vbench_validation_predictor.sh" \
+    "$eval_name" "$checkpoint" 1,52 v4 1,2 "$mode" concat
+  record_status complete "$eval_name"
+}
+
+run_eval none none
+run_eval previous-step previous_step
+run_eval both both
+
+record_status complete all
+date -u +%FT%TZ >"$run_root/all.completed"
+aws s3 sync "$run_root" \
+  "s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/logs/stage1_previous_condition_validation_${run_tag}" \
+  --only-show-errors
+echo "[complete] all previous-condition validation evaluations"

tools/run_vbench_atc_validation25.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+vbench_repo="${VBENCH_REPO:-/mnt/local_nvme/cz/projects/VBench}"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay_july20260720/bin/python}"
+vbench_site_packages="${VBENCH_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/vbench_eval/lib/python3.10/site-packages}"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-${repo_root}/datasets/${dataset_name}}"
+run_name="validation25_atc_ablation_oldenv"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/${run_name}"
+overlay_root="${run_root}/site_overlay"
+self_forcing_site_packages="${SELF_FORCING_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/self_forcing/lib/python3.10/site-packages}"
+
+mkdir -p "${overlay_root}"
+for package in easydict timm open_clip; do
+  [[ -d "${self_forcing_site_packages}/${package}" ]]
+  ln -sfn "${self_forcing_site_packages}/${package}" "${overlay_root}/${package}"
+done
+
+export PYTHONPATH="${overlay_root}:${vbench_site_packages}:${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="${VBENCH_CACHE_DIR:-/mnt/local_nvme/cz/.cache/vbench}"
+export TORCH_HOME="${TORCH_HOME:-/mnt/local_nvme/cz/.cache/torch}"
+export HF_HOME="${HF_HOME:-/mnt/local_nvme/cz/.cache/huggingface}"
+export OMP_NUM_THREADS="${OMP_NUM_THREADS:-4}"
+
+[[ -x "${python_bin}" ]]
+[[ -f "${vbench_repo}/evaluate.py" ]]
+[[ -f "${dataset_root}/validation/cases.jsonl" ]]
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+groups=()
+group_names=()
+for variant in full anchor_only raw_prev no_gate no_distance; do
+  for schedule in fppf fppp; do
+    group="atc_${variant}_${schedule}"
+    eval_name="eval_validation25_atc-${variant}_schedule-${schedule}_blocks1-52_step2000_oldenv"
+    groups+=("${group}|${dataset_root}/evaluations/${eval_name}/predictor")
+    group_names+=("${group}")
+  done
+done
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  video_count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  if [[ "${video_count}" -ne 100 ]]; then
+    echo "${label}: expected 100 videos, found ${video_count}: ${source_dir}" >&2
+    exit 1
+  fi
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+
+expected_records=1000
+staged_count=$(find "${staging_root}" -maxdepth 1 -type l | wc -l)
+if [[ "${staged_count}" -ne "${expected_records}" ]]; then
+  echo "Expected ${expected_records} staged videos, found ${staged_count}" >&2
+  exit 1
+fi
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count "${expected_records}"
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" "${expected_records}" <<'PY'
+import json
+import sys
+
+path, dimension, expected_records = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == int(expected_records), (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  if [[ "${PREDICTOR_SKIP_SYNC:-0}" != "1" ]]; then
+    aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  fi
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+summary_args=()
+for group in "${group_names[@]}"; do
+  summary_args+=(--group "${group}")
+done
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  "${summary_args[@]}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+if [[ "${PREDICTOR_SKIP_SYNC:-0}" != "1" ]]; then
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+fi
+echo "[vbench] all ATC dimensions complete: ${run_root}"

tools/run_vbench_c1_threshold_validation25.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+vbench_repo="${VBENCH_REPO:-/mnt/local_nvme/cz/projects/VBench}"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/self_forcing/bin/python3.10}"
+vbench_site_packages="${VBENCH_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/vbench_eval/lib/python3.10/site-packages}"
+dataset_root="${repo_root}/datasets/hyworldplay_predictor_vbench_val25_test50"
+run_root="${dataset_root}/vbench/validation25_c1_thresholds"
+staging_root="${dataset_root}/vbench_staging/validation25_c1_thresholds"
+
+export PYTHONPATH="${vbench_site_packages}:${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="${VBENCH_CACHE_DIR:-/mnt/local_nvme/cz/.cache/vbench}"
+export TORCH_HOME="${TORCH_HOME:-/mnt/local_nvme/cz/.cache/torch}"
+export HF_HOME="${HF_HOME:-/mnt/local_nvme/cz/.cache/huggingface}"
+
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+groups=(
+  "c1_r10|${dataset_root}/evaluations/eval_validation25_stage1-c1-threshold-r10_blocks1-52_fp32master_step2000/predictor"
+  "c1_r25|${dataset_root}/evaluations/eval_validation25_stage1-c1-threshold-r25_blocks1-52_fp32master_step2000/predictor"
+  "c1_r33|${dataset_root}/evaluations/eval_validation25_stage1-c1-threshold-r33_blocks1-52_fp32master_step2000/predictor"
+  "c1_r50|${dataset_root}/evaluations/eval_validation25_stage1-c1-threshold-r50_blocks1-52_fp32master_step2000/predictor"
+)
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  [[ $(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l) -eq 100 ]]
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+[[ $(find "${staging_root}" -maxdepth 1 -type l | wc -l) -eq 400 ]]
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count 400
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  if [[ -f "${marker}" ]] \
+    && [[ $(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l) -eq 1 ]]; then
+    echo "[skip] ${dimension}"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json, sys
+path, dimension = sys.argv[1:]
+records = json.load(open(path))[dimension][1]
+assert len(records) == 400, (dimension, len(records))
+print(dimension, len(records))
+PY
+  date -u +%FT%TZ >"${marker}"
+done
+
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  --group c1_r10 --group c1_r25 --group c1_r33 --group c1_r50 \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+echo "[vbench] all C1 threshold dimensions complete: ${run_root}"

tools/run_vbench_previous_condition_none_step0300_validation25.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+vbench_repo="${VBENCH_REPO:-/mnt/local_nvme/cz/projects/VBench}"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay_july20260720/bin/python}"
+vbench_site_packages="${VBENCH_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/vbench_eval/lib/python3.10/site-packages}"
+self_forcing_site_packages="${SELF_FORCING_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/self_forcing/lib/python3.10/site-packages}"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-${repo_root}/datasets/${dataset_name}}"
+run_name="validation25_previous_condition_none_step0300_torch26_20260825"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+source_dir="${dataset_root}/evaluations/eval_validation25_previous-condition-none-step0300_force-first-chunk-ffff_torch26_20260824/predictor"
+group="none_step0300_first_chunk_ffff"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/${run_name}"
+overlay_root="${run_root}/site_overlay"
+
+mkdir -p "${overlay_root}"
+for package in easydict timm open_clip; do
+  [[ -d "${self_forcing_site_packages}/${package}" ]]
+  ln -sfn "${self_forcing_site_packages}/${package}" "${overlay_root}/${package}"
+done
+
+export PYTHONPATH="${overlay_root}:${vbench_site_packages}:${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="${VBENCH_CACHE_DIR:-/mnt/local_nvme/cz/.cache/vbench}"
+export TORCH_HOME="${TORCH_HOME:-/mnt/local_nvme/cz/.cache/torch}"
+export HF_HOME="${HF_HOME:-/mnt/local_nvme/cz/.cache/huggingface}"
+export OMP_NUM_THREADS="${OMP_NUM_THREADS:-4}"
+
+[[ -x "${python_bin}" ]]
+[[ -f "${vbench_repo}/evaluate.py" ]]
+[[ -f "${dataset_root}/validation/cases.jsonl" ]]
+[[ $(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l) -eq 100 ]]
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+while IFS= read -r video_path; do
+  ln -s "${video_path}" "${staging_root}/${group}__$(basename "${video_path}")"
+done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+[[ $(find "${staging_root}" -maxdepth 1 -type l | wc -l) -eq 100 ]]
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count 100
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json
+import sys
+
+path, dimension = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == 100, (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  if [[ "${PREDICTOR_SKIP_SYNC:-0}" != "1" ]]; then
+    aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  fi
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  --group "${group}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+if [[ "${PREDICTOR_SKIP_SYNC:-0}" != "1" ]]; then
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+fi
+echo "[vbench] none step0300 complete: ${run_root}"

tools/run_vbench_previous_condition_validation25.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+vbench_repo="${VBENCH_REPO:-/mnt/local_nvme/cz/projects/VBench}"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay_july20260720/bin/python}"
+vbench_site_packages="${VBENCH_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/vbench_eval/lib/python3.10/site-packages}"
+self_forcing_site_packages="${SELF_FORCING_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/self_forcing/lib/python3.10/site-packages}"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-${repo_root}/datasets/${dataset_name}}"
+run_name="validation25_previous_condition_torch26_20260824"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/${run_name}"
+overlay_root="${run_root}/site_overlay"
+
+mkdir -p "${overlay_root}"
+for package in easydict timm open_clip; do
+  [[ -d "${self_forcing_site_packages}/${package}" ]]
+  ln -sfn "${self_forcing_site_packages}/${package}" "${overlay_root}/${package}"
+done
+
+export PYTHONPATH="${overlay_root}:${vbench_site_packages}:${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="${VBENCH_CACHE_DIR:-/mnt/local_nvme/cz/.cache/vbench}"
+export TORCH_HOME="${TORCH_HOME:-/mnt/local_nvme/cz/.cache/torch}"
+export HF_HOME="${HF_HOME:-/mnt/local_nvme/cz/.cache/huggingface}"
+export OMP_NUM_THREADS="${OMP_NUM_THREADS:-4}"
+
+[[ -x "${python_bin}" ]]
+[[ -f "${vbench_repo}/evaluate.py" ]]
+[[ -f "${dataset_root}/validation/cases.jsonl" ]]
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+groups=(
+  "same_step_step2000|${dataset_root}/evaluations/eval_validation25_v4_blocks1-52_fp32master_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100/predictor"
+  "previous_step_step2000|${dataset_root}/evaluations/eval_validation25_previous-condition-previous-step_torch26-retrain_20260824/predictor"
+  "both_step2000|${dataset_root}/evaluations/eval_validation25_previous-condition-both_torch26-retrain_20260824/predictor"
+  "none_step2000_first_chunk_fppf|${dataset_root}/evaluations/eval_validation25_previous-condition-none_torch26-retrain_20260824/predictor"
+  "none_step0500_first_chunk_ffff|${dataset_root}/evaluations/eval_validation25_previous-condition-none-step0500_force-first-chunk-ffff_torch26_20260824/predictor"
+  "none_step1000_first_chunk_ffff|${dataset_root}/evaluations/eval_validation25_previous-condition-none-step1000_force-first-chunk-ffff_torch26_20260824/predictor"
+  "none_step2000_first_chunk_ffff|${dataset_root}/evaluations/eval_validation25_previous-condition-none_force-first-chunk-ffff_torch26_20260824/predictor"
+)
+group_names=()
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  group_names+=("${label}")
+  video_count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  if [[ "${video_count}" -ne 100 ]]; then
+    echo "${label}: expected 100 videos, found ${video_count}: ${source_dir}" >&2
+    exit 1
+  fi
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+
+expected_records=700
+staged_count=$(find "${staging_root}" -maxdepth 1 -type l | wc -l)
+if [[ "${staged_count}" -ne "${expected_records}" ]]; then
+  echo "Expected ${expected_records} staged videos, found ${staged_count}" >&2
+  exit 1
+fi
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count "${expected_records}"
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" "${expected_records}" <<'PY'
+import json
+import sys
+
+path, dimension, expected_records = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == int(expected_records), (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  if [[ "${PREDICTOR_SKIP_SYNC:-0}" != "1" ]]; then
+    aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  fi
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+summary_args=()
+for group in "${group_names[@]}"; do
+  summary_args+=(--group "${group}")
+done
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  "${summary_args[@]}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+if [[ "${PREDICTOR_SKIP_SYNC:-0}" != "1" ]]; then
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+fi
+echo "[vbench] all previous-condition dimensions complete: ${run_root}"

tools/run_vbench_token_gate_validation25.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+vbench_repo="${VBENCH_REPO:-/mnt/local_nvme/cz/projects/VBench}"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/self_forcing/bin/python3.10}"
+vbench_site_packages="${VBENCH_SITE_PACKAGES:-/mnt/local_nvme/cz/envs/vbench_eval/lib/python3.10/site-packages}"
+dataset_root="${repo_root}/datasets/hyworldplay_predictor_vbench_val25_test50"
+source_dir="${dataset_root}/evaluations/eval_validation25_stage1-token-gate-prev_schedule-fppf_blocks1-52_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100/predictor"
+run_root="${dataset_root}/vbench/validation25_token_gate_prev_fppf"
+staging_root="${dataset_root}/vbench_staging/validation25_token_gate_prev_fppf"
+group=token_gate_prev_fppf
+
+export PYTHONPATH="${vbench_site_packages}:${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="${VBENCH_CACHE_DIR:-/mnt/local_nvme/cz/.cache/vbench}"
+export TORCH_HOME="${TORCH_HOME:-/mnt/local_nvme/cz/.cache/torch}"
+export HF_HOME="${HF_HOME:-/mnt/local_nvme/cz/.cache/huggingface}"
+
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+find "${staging_root}" -maxdepth 1 -type l -delete
+[[ $(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l) -eq 100 ]]
+while IFS= read -r video_path; do
+  ln -s "${video_path}" "${staging_root}/${group}__$(basename "${video_path}")"
+done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+[[ $(find "${staging_root}" -maxdepth 1 -type l | wc -l) -eq 100 ]]
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count 100
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  if [[ -f "${marker}" ]] \
+    && [[ $(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l) -eq 1 ]]; then
+    echo "[skip] ${dimension}"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json, sys
+path, dimension = sys.argv[1:]
+records = json.load(open(path))[dimension][1]
+assert len(records) == 100, (dimension, len(records))
+print(dimension, len(records))
+PY
+  date -u +%FT%TZ >"${marker}"
+done
+
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" \
+  --run_root "${run_root}" \
+  --group "${group}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+echo "[vbench] token-gate validation complete: ${run_root}"

tools/run_vbench_validation25_chunk_timestep_step2000.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+vbench_repo="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/VBench"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/${dataset_name}}"
+run_name="validation25_chunk_timestep_step2000"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/${run_name}"
+
+export PYTHONPATH="${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/vbench"
+export TORCH_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/torch"
+export HF_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/huggingface"
+
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+declare -a groups=(
+  "chunk_timestep_step2000_fppf|${dataset_root}/evaluations/eval_validation25_detached-chunk-timestep-rollout-onpolicy-fppp-fulltrain100_schedule-fppf_blocks1-52_ckptstep2000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1/predictor"
+  "chunk_timestep_step2000_fppp|${dataset_root}/evaluations/eval_validation25_detached-chunk-timestep-rollout-onpolicy-fppp-fulltrain100_schedule-fppp_blocks1-52_ckptstep2000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1/predictor"
+)
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  video_count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  if [[ "${video_count}" -ne 100 ]]; then
+    echo "${label}: expected 100 videos, found ${video_count}: ${source_dir}" >&2
+    exit 1
+  fi
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+
+staged_count=$(find "${staging_root}" -maxdepth 1 -type l | wc -l)
+if [[ "${staged_count}" -ne 200 ]]; then
+  echo "Expected 200 staged videos, found ${staged_count}" >&2
+  exit 1
+fi
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}" \
+  --expected_count 200
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json
+import sys
+
+path, dimension = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == 200, (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+"${python_bin}" \
+  "${repo_root}/tools/summarize_vbench_validation25_chunk_timestep_step2000.py" \
+  --run_root "${run_root}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+echo "[vbench] all dimensions complete: ${run_root}"

tools/run_vbench_validation25_core.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+vbench_repo="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/VBench"
+dataset_name="hyworldplay_predictor_vbench_val25_test50"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/${dataset_name}}"
+run_root="${dataset_root}/vbench/validation25_core8"
+staging_root="${dataset_root}/vbench_staging/validation25_core8"
+python_bin="/mnt/s3files/s3-us-west2-default/zoubin/cz/envs/hy_worldplay/bin/python"
+durable_uri="s3://s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}/vbench/validation25_core8"
+
+export PYTHONPATH="${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/vbench"
+export TORCH_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/torch"
+export HF_HOME="/mnt/s3files/s3-us-west2-default/zoubin/cz/.cache/huggingface"
+
+mkdir -p "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+
+declare -a groups=(
+  "full_ffff|${dataset_root}/validation/full"
+  "reuse_frrf|${dataset_root}/validation/reuse"
+  "stage1_fppf|${dataset_root}/evaluations/eval_validation25_v4_blocks1-52_fp32master_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100/predictor"
+  "stage1_fppp|${dataset_root}/evaluations/eval_validation25_stage1-v4_schedule-fppp_blocks1-52_fp32master_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100/predictor"
+  "timestep_onpolicy_fppf|${dataset_root}/evaluations/eval_validation25_detached-timestep-rollout-onpolicy-fulltrain100_schedule-fppf_blocks1-52_ckptstep1000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1/predictor"
+  "timestep_onpolicy_fppp|${dataset_root}/evaluations/eval_validation25_detached-timestep-rollout-onpolicy-fulltrain100_schedule-fppp_blocks1-52_ckptstep1000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1/predictor"
+  "chunk_timestep_fppf|${dataset_root}/evaluations/eval_validation25_detached-chunk-timestep-rollout-onpolicy-fppp-fulltrain100_schedule-fppf_blocks1-52_ckptstep1000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1/predictor"
+  "chunk_timestep_fppp|${dataset_root}/evaluations/eval_validation25_detached-chunk-timestep-rollout-onpolicy-fppp-fulltrain100_schedule-fppp_blocks1-52_ckptstep1000_flr5e-5_blr5e-6_schedsteps2000_swarmup100_bwarmup100linear_bs1/predictor"
+)
+
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${groups[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  video_count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  if [[ "${video_count}" -ne 100 ]]; then
+    echo "${label}: expected 100 videos, found ${video_count}: ${source_dir}" >&2
+    exit 1
+  fi
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+done
+
+staged_count=$(find "${staging_root}" -maxdepth 1 -type l | wc -l)
+if [[ "${staged_count}" -ne 800 ]]; then
+  echo "Expected 800 staged videos, found ${staged_count}" >&2
+  exit 1
+fi
+
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" \
+  --staging_root "${staging_root}" \
+  --output "${prompt_file}"
+
+dimensions=(
+  subject_consistency
+  background_consistency
+  temporal_flickering
+  motion_smoothness
+  dynamic_degree
+  aesthetic_quality
+  imaging_quality
+  overall_consistency
+)
+
+for dimension in "${dimensions[@]}"; do
+  output_dir="${run_root}/raw/${dimension}"
+  marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  result_count=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l)
+  if [[ -f "${marker}" && "${result_count}" -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"
+    continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run \
+    --standalone \
+    --nproc_per_node=8 \
+    "${vbench_repo}/evaluate.py" \
+    --videos_path "${staging_root}" \
+    --dimension "${dimension}" \
+    --mode custom_input \
+    --prompt_file "${prompt_file}" \
+    --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer \
+    --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" <<'PY'
+import json
+import sys
+
+path, dimension = sys.argv[1:]
+payload = json.load(open(path))
+records = payload[dimension][1]
+assert len(records) == 800, (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_core.py" \
+  --run_root "${run_root}" \
+  >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+aws s3 sync "${run_root}" "${durable_uri}" --only-show-errors
+echo "[vbench] all dimensions complete: ${run_root}"

tools/run_vbench_validation25_groups.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Generic VBench (8 dimensions) over staged validation25 groups.
+#   RUN_NAME=<name> NPROC=4 VBENCH_GROUPS="label|dir ..." bash tools/run_vbench_validation25_groups.sh
+# VBENCH_GROUPS entries are "label|<eval_root>/predictor" separated by spaces; each dir
+# must hold exactly 100 mp4s.  Local paths; no S3 sync.
+set -euo pipefail
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+vbench_repo="${VBENCH_REPO:-/local/zoubin/cz/projects/VBench}"
+python_bin="${PREDICTOR_PYTHON_BIN:-/local/zoubin/cz/envs/hy_worldplay_july20260720/bin/python}"
+vbench_site_packages="${VBENCH_SITE_PACKAGES:-/local/zoubin/cz/envs/vbench_eval/lib/python3.10/site-packages}"
+self_forcing_site_packages="${SELF_FORCING_SITE_PACKAGES:-/local/zoubin/cz/envs/self_forcing/lib/python3.10/site-packages}"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-${repo_root}/datasets/hyworldplay_predictor_vbench_val25_test50}"
+run_name="${RUN_NAME:?set RUN_NAME}"
+nproc="${NPROC:-8}"
+run_root="${dataset_root}/vbench/${run_name}"
+staging_root="${dataset_root}/vbench_staging/${run_name}"
+overlay_root="${run_root}/site_overlay"
+mkdir -p "${overlay_root}" "${run_root}/raw" "${run_root}/logs" "${staging_root}"
+for package in easydict timm open_clip; do
+  [[ -d "${self_forcing_site_packages}/${package}" ]]
+  ln -sfn "${self_forcing_site_packages}/${package}" "${overlay_root}/${package}"
+done
+export PYTHONPATH="${overlay_root}:${vbench_site_packages}:${vbench_repo}:${repo_root}"
+export VBENCH_CACHE_DIR="/local/zoubin/cz/.cache/vbench"
+export TORCH_HOME="/local/zoubin/cz/.cache/torch"
+export TORCH_HUB="${TORCH_HOME}/hub"   # torch.hub reads TORCH_HUB first; the login shell sets it to /mnt/local_nvme
+export HF_HOME="/local/zoubin/cz/.cache/huggingface"
+export OMP_NUM_THREADS="${OMP_NUM_THREADS:-4}"
+[[ -x "${python_bin}" && -f "${vbench_repo}/evaluate.py" && -f "${dataset_root}/validation/cases.jsonl" ]]
+read -r -a group_specs <<< "${VBENCH_GROUPS:?set VBENCH_GROUPS}"
+group_names=()
+find "${staging_root}" -maxdepth 1 -type l -delete
+for spec in "${group_specs[@]}"; do
+  IFS='|' read -r label source_dir <<<"${spec}"
+  count=$(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | wc -l)
+  [[ "${count}" -eq 100 ]] || { echo "${label}: expected 100 videos, found ${count}: ${source_dir}" >&2; exit 1; }
+  while IFS= read -r video_path; do
+    ln -s "${video_path}" "${staging_root}/${label}__$(basename "${video_path}")"
+  done < <(find "${source_dir}" -maxdepth 1 -type f -name '*.mp4' | sort)
+  group_names+=("${label}")
+done
+expected_records=$(( ${#group_names[@]} * 100 ))
+[[ $(find "${staging_root}" -maxdepth 1 -type l | wc -l) -eq "${expected_records}" ]]
+prompt_file="${run_root}/validation25_prompt_map.json"
+"${python_bin}" "${repo_root}/tools/build_vbench_validation25_prompt_map.py" \
+  --cases_jsonl "${dataset_root}/validation/cases.jsonl" --staging_root "${staging_root}" \
+  --output "${prompt_file}" --expected_count "${expected_records}"
+for dimension in subject_consistency background_consistency temporal_flickering motion_smoothness dynamic_degree aesthetic_quality imaging_quality overall_consistency; do
+  output_dir="${run_root}/raw/${dimension}"; marker="${run_root}/${dimension}.completed"
+  mkdir -p "${output_dir}"
+  if [[ -f "${marker}" && $(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json' | wc -l) -eq 1 ]]; then
+    echo "[skip] ${dimension} already complete"; continue
+  fi
+  find "${output_dir}" -maxdepth 1 -type f -delete
+  echo "[vbench] ${dimension} start $(date -u +%FT%TZ)"
+  "${python_bin}" -m torch.distributed.run --standalone --nproc_per_node="${nproc}" \
+    "${vbench_repo}/evaluate.py" --videos_path "${staging_root}" --dimension "${dimension}" \
+    --mode custom_input --prompt_file "${prompt_file}" --load_ckpt_from_local True \
+    --imaging_quality_preprocessing_mode longer --output_path "${output_dir}" \
+    >"${run_root}/logs/${dimension}.log" 2>&1
+  result_json=$(find "${output_dir}" -maxdepth 1 -type f -name '*_eval_results.json')
+  "${python_bin}" - "${result_json}" "${dimension}" "${expected_records}" <<'PY'
+import json, sys
+path, dimension, expected = sys.argv[1:]
+payload = json.load(open(path)); records = payload[dimension][1]
+assert len(records) == int(expected), (dimension, len(records))
+print(dimension, len(records), payload[dimension][0])
+PY
+  date -u +%FT%TZ >"${marker}"
+  echo "[vbench] ${dimension} complete $(date -u +%FT%TZ)"
+done
+summary_args=(); for group in "${group_names[@]}"; do summary_args+=(--group "${group}"); done
+"${python_bin}" "${repo_root}/tools/summarize_vbench_validation25_pair.py" --run_root "${run_root}" "${summary_args[@]}" >"${run_root}/logs/summary.log" 2>&1
+date -u +%FT%TZ >"${run_root}/pipeline.completed"
+echo "[vbench] complete: ${run_root}"

tools/run_wide_c1_r33_validation25_reference.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay/bin/python3.10}"
+dataset_root="${repo_root}/datasets/hyworldplay_predictor_vbench_val25_test50"
+validation_root="${dataset_root}/validation"
+base_model="${repo_root}/outputs/hf_snapshot_repaired_9b49404"
+action_ckpt="/mnt/local_nvme/cz/checkpoints/hy_worldplay/huggingface/hub/models--tencent--HY-WorldPlay/snapshots/f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/diffusion_pytorch_model.safetensors"
+weights="${repo_root}/checkpoints/predictor_v4_prefeature_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors"
+confidence_checkpoint="${repo_root}/confidence_validation_wide4096x2_c1/checkpoints/confidence_c1.pt"
+confidence_threshold="-4.308430990"
+eval_name="eval_validation25_stage1-wide4096x2-c1-threshold-r33_blocks1-52_fp32master_step2000"
+eval_root="${dataset_root}/evaluations/${eval_name}"
+log_dir="${eval_root}/logs"
+
+export PYTHONPATH="${repo_root}"
+export HY_PROFILE_TIMING=1
+mkdir -p "${log_dir}"
+
+run_workers() {
+  local phase="$1"
+  shift
+  local -a pids=()
+  local worker_id
+  for worker_id in $(seq 0 7); do
+    CUDA_VISIBLE_DEVICES="${worker_id}" "${python_bin}" -u "$@" \
+      --worker_id "${worker_id}" --num_workers 8 \
+      >"${log_dir}/${phase}_worker_${worker_id}.log" 2>&1 &
+    pids+=("$!")
+  done
+  local failed=0 pid
+  for pid in "${pids[@]}"; do
+    if ! wait "${pid}"; then failed=1; fi
+  done
+  if [[ "${failed}" -ne 0 ]]; then
+    echo "${phase} worker failure; inspect ${log_dir}/${phase}_worker_*.log" >&2
+    return 1
+  fi
+}
+
+if [[ ! -f "${eval_root}/generation.completed" ]] \
+  || [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' 2>/dev/null | wc -l) -ne 100 ]]; then
+  date -u +%FT%TZ >"${eval_root}/generation.started"
+  run_workers generate \
+    "${repo_root}/tools/generate_predictor_v4_train_case_eval.py" \
+    --dataset_root "${validation_root}" \
+    --output_root "${eval_root}" \
+    --base_model "${base_model}" \
+    --action_ckpt "${action_ckpt}" \
+    --weights "${weights}" \
+    --source_blocks 1,52 \
+    --predictor_variant v4 \
+    --previous_condition_mode same_step \
+    --replace_steps 1,2,3 \
+    --modes predictor \
+    --confidence_checkpoint "${confidence_checkpoint}" \
+    --confidence_threshold "${confidence_threshold}"
+  [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' | wc -l) -eq 100 ]]
+  date -u +%FT%TZ >"${eval_root}/generation.completed"
+fi
+
+if [[ ! -f "${eval_root}/metrics.completed" ]]; then
+  date -u +%FT%TZ >"${eval_root}/metrics.started"
+  run_workers metrics \
+    "${repo_root}/tools/compute_predictor_v4_train_case_metrics.py" \
+    --dataset_root "${validation_root}" \
+    --output_root "${eval_root}" \
+    --num_cases 25 \
+    --reference_subdir full \
+    --modes predictor \
+    --metric_batch_size 4
+  "${python_bin}" "${repo_root}/tools/merge_predictor_v4_train_case_metrics.py" \
+    --output_root "${eval_root}" \
+    --num_workers 8 \
+    --num_cases 25 \
+    --modes predictor \
+    --replace_steps 1,2,3 \
+    --reference_label "Full-DiT validation videos" \
+    >"${log_dir}/metrics_merge.log" 2>&1
+  date -u +%FT%TZ >"${eval_root}/metrics.completed"
+fi
+
+echo "Validation evaluation complete: ${eval_root}"

tools/run_wide_c2_hybrid_validation25_reference.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+python_bin="${PREDICTOR_PYTHON_BIN:-/mnt/local_nvme/cz/envs/hy_worldplay/bin/python3.10}"
+dataset_root="${repo_root}/datasets/hyworldplay_predictor_vbench_val25_test50"
+validation_root="${dataset_root}/validation"
+base_model="${repo_root}/outputs/hf_snapshot_repaired_9b49404"
+action_ckpt="/mnt/local_nvme/cz/checkpoints/hy_worldplay/huggingface/hub/models--tencent--HY-WorldPlay/snapshots/f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/diffusion_pytorch_model.safetensors"
+weights="${repo_root}/checkpoints/predictor_v4_prefeature_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors"
+confidence_checkpoint="${repo_root}/confidence_validation_wide4096x2_c2/checkpoints/confidence_c2.pt"
+
+tags=(p12r10 p12r25)
+thresholds=(
+  "1:-4.136674309,2:-3.798280764"
+  "1:-4.400576830,2:-4.049407601"
+)
+gpu_groups=("0 1 2 3" "4 5 6 7")
+
+export PYTHONPATH="${repo_root}"
+export HY_PROFILE_TIMING=1
+
+run_group() {
+  local phase="$1" group_index="$2"
+  local tag="${tags[$group_index]}"
+  local threshold_spec="${thresholds[$group_index]}"
+  local eval_name="eval_validation25_stage1-wide4096x2-c2-hybrid-p3full-${tag}_blocks1-52_fp32master_step2000"
+  local eval_root="${dataset_root}/evaluations/${eval_name}"
+  local log_dir="${eval_root}/logs"
+  local -a gpus=(${gpu_groups[$group_index]})
+  mkdir -p "${log_dir}"
+
+  if [[ "${phase}" == "generate" ]] \
+    && [[ -f "${eval_root}/generation.completed" ]] \
+    && [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' 2>/dev/null | wc -l) -eq 100 ]]; then
+    return
+  fi
+  if [[ "${phase}" == "metrics" && -f "${eval_root}/metrics.completed" ]]; then
+    return
+  fi
+
+  local worker_id gpu failed=0 pid
+  local -a pids=()
+  for worker_id in "${!gpus[@]}"; do
+    gpu="${gpus[$worker_id]}"
+    if [[ "${phase}" == "generate" ]]; then
+      CUDA_VISIBLE_DEVICES="${gpu}" "${python_bin}" -u \
+        "${repo_root}/tools/generate_predictor_v4_train_case_eval.py" \
+        --dataset_root "${validation_root}" \
+        --output_root "${eval_root}" \
+        --base_model "${base_model}" \
+        --action_ckpt "${action_ckpt}" \
+        --weights "${weights}" \
+        --source_blocks 1,52 \
+        --predictor_variant v4 \
+        --previous_condition_mode same_step \
+        --replace_steps 1,2 \
+        --modes predictor \
+        --confidence_checkpoint "${confidence_checkpoint}" \
+        --confidence_thresholds "${threshold_spec}" \
+        --worker_id "${worker_id}" --num_workers "${#gpus[@]}" \
+        >"${log_dir}/generate_worker_${worker_id}.log" 2>&1 &
+    else
+      CUDA_VISIBLE_DEVICES="${gpu}" "${python_bin}" -u \
+        "${repo_root}/tools/compute_predictor_v4_train_case_metrics.py" \
+        --dataset_root "${validation_root}" \
+        --output_root "${eval_root}" \
+        --num_cases 25 \
+        --reference_subdir full \
+        --modes predictor \
+        --metric_batch_size 4 \
+        --worker_id "${worker_id}" --num_workers "${#gpus[@]}" \
+        >"${log_dir}/metrics_worker_${worker_id}.log" 2>&1 &
+    fi
+    pids+=("$!")
+  done
+  for pid in "${pids[@]}"; do
+    if ! wait "${pid}"; then failed=1; fi
+  done
+  if [[ "${failed}" -ne 0 ]]; then
+    echo "${phase} failed for ${tag}; inspect ${log_dir}" >&2
+    return 1
+  fi
+
+  if [[ "${phase}" == "generate" ]]; then
+    [[ $(find "${eval_root}/predictor" -type f -name '*.mp4' | wc -l) -eq 100 ]]
+    date -u +%FT%TZ >"${eval_root}/generation.completed"
+  else
+    "${python_bin}" "${repo_root}/tools/merge_predictor_v4_train_case_metrics.py" \
+      --output_root "${eval_root}" \
+      --num_workers "${#gpus[@]}" \
+      --num_cases 25 \
+      --modes predictor \
+      --replace_steps 1,2 \
+      --reference_label "Full-DiT validation videos" \
+      >"${log_dir}/metrics_merge.log" 2>&1
+    date -u +%FT%TZ >"${eval_root}/metrics.completed"
+  fi
+}
+
+run_phase() {
+  local phase="$1" failed=0 pid group_index
+  local -a pids=()
+  for group_index in "${!tags[@]}"; do
+    run_group "${phase}" "${group_index}" &
+    pids+=("$!")
+  done
+  for pid in "${pids[@]}"; do
+    if ! wait "${pid}"; then failed=1; fi
+  done
+  [[ "${failed}" -eq 0 ]]
+}
+
+run_phase generate
+run_phase metrics
+echo "Wide C2 hybrid validation25 evaluation complete"

tools/summarize_atc_rollout_ckpt_sweep.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+"""Full-reference metrics + VBench Core5 table for the ATC rollout checkpoint sweep."""
+from __future__ import annotations
+import argparse, json
+from pathlib import Path
+
+CORE5 = ("subject_consistency", "background_consistency", "motion_smoothness", "aesthetic_quality", "imaging_quality")
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--dataset_root", type=Path, required=True)
+    p.add_argument("--vbench_run", required=True)
+    p.add_argument("--group", action="append", required=True, help="label|eval_dir_name")
+    p.add_argument("--output", type=Path, required=True)
+    args = p.parse_args()
+    vb = json.load(open(args.dataset_root / "vbench" / args.vbench_run / "summary.json"))
+    groups = vb.get("groups", vb)
+    rows = []
+    for spec in args.group:
+        label, eval_name = spec.split("|", 1)
+        m = json.load(open(args.dataset_root / "evaluations" / eval_name / "metrics.json"))["summary_mean"]["predictor"]
+        g = groups.get(label, {}).get("mean", {})
+        core5 = sum(g[d] / (100.0 if d == "imaging_quality" and g[d] > 1.5 else 1.0) for d in CORE5) / 5 if all(d in g for d in CORE5) else float("nan")
+        rows.append({"label": label, "psnr": m["psnr_db"], "frame_psnr": m["frame_psnr_mean_db"], "ssim": m["ssim"],
+                     "lpips": m["lpips_alex"], "mse": m["pixel_mse"], "temporal_mse": m["temporal_delta_mse"],
+                     "vbench_core5": core5, **{f"vbench_{d}": g.get(d, float("nan")) for d in g}})
+    lines = ["| 组 | PSNR ↑ | Frame PSNR ↑ | SSIM ↑ | LPIPS ↓ | MSE ↓ | Temporal MSE ↓ | VBench Core5 ↑ |", "|---|---:|---:|---:|---:|---:|---:|---:|"]
+    for r in rows:
+        lines.append(f"| {r['label']} | {r['psnr']:.4f} | {r['frame_psnr']:.4f} | {r['ssim']:.5f} | {r['lpips']:.5f} | {r['mse']:.6f} | {r['temporal_mse']:.6f} | {r['vbench_core5']:.6f} |")
+    args.output.with_suffix(".json").write_text(json.dumps(rows, indent=2) + "\n")
+    args.output.write_text("\n".join(lines) + "\n")
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()

tools/summarize_c1_threshold_validation25.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Summarize Stage-1 C1-threshold validation25 reference metrics and routing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+DATASET = ROOT / "datasets/hyworldplay_predictor_vbench_val25_test50"
+EVALUATIONS = DATASET / "evaluations"
+OUTPUT = ROOT / "confidence_validation/c1_threshold_validation25"
+BASELINES = {
+    "FFFF": None,
+    "FPPF": "eval_validation25_v4_blocks1-52_fp32master_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100",
+    "FPPP": "eval_validation25_stage1-v4_schedule-fppp_blocks1-52_fp32master_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100",
+}
+THRESHOLDS = {
+    "C1-r10": ("eval_validation25_stage1-c1-threshold-r10_blocks1-52_fp32master_step2000", -3.523588657),
+    "C1-r25": ("eval_validation25_stage1-c1-threshold-r25_blocks1-52_fp32master_step2000", -3.915276289),
+    "C1-r33": ("eval_validation25_stage1-c1-threshold-r33_blocks1-52_fp32master_step2000", -4.329442501),
+    "C1-r50": ("eval_validation25_stage1-c1-threshold-r50_blocks1-52_fp32master_step2000", -4.798926830),
+}
+METRICS = (
+    "psnr_db", "frame_psnr_mean_db", "ssim", "lpips_alex", "pixel_mae",
+    "pixel_mse", "pixel_rmse", "temporal_delta_mse",
+)
+VBENCH_DIMENSIONS = (
+    "subject_consistency", "background_consistency", "temporal_flickering",
+    "motion_smoothness", "dynamic_degree", "aesthetic_quality",
+    "imaging_quality", "overall_consistency",
+)
+VBENCH_CORE5 = (
+    "subject_consistency", "background_consistency", "motion_smoothness",
+    "aesthetic_quality", "imaging_quality",
+)
+
+
+def read_metrics(eval_name: str) -> dict:
+    payload = json.loads((EVALUATIONS / eval_name / "metrics.json").read_text())
+    return payload["summary_mean"]["predictor"]
+
+
+def read_decisions(eval_name: str) -> tuple[list[dict], list[float]]:
+    root = EVALUATIONS / eval_name
+    decisions = []
+    for path in sorted((root / "confidence_decisions").glob("worker_*.jsonl")):
+        decisions.extend(json.loads(line) for line in path.read_text().splitlines())
+    elapsed = []
+    for path in sorted((root / "logs").glob("worker_*.jsonl")):
+        elapsed.extend(json.loads(line)["elapsed_s"] for line in path.read_text().splitlines())
+    return decisions, elapsed
+
+
+def main() -> None:
+    rows = []
+    rows.append({
+        "method": "FFFF", "threshold_log_c1": None, "fallback_rate": 1.0,
+        **{name: (float("inf") if "psnr" in name else 1.0 if name == "ssim" else 0.0) for name in METRICS},
+    })
+    for method in ("FPPF", "FPPP"):
+        fallback = 1 / 3 if method == "FPPF" else 0.0
+        rows.append({
+            "method": method, "threshold_log_c1": None,
+            "fallback_rate": fallback, **read_metrics(BASELINES[method]),
+        })
+    for method, (eval_name, threshold) in THRESHOLDS.items():
+        decisions, elapsed = read_decisions(eval_name)
+        fallback = [item for item in decisions if item["fallback_to_full"]]
+        by_step = {
+            f"p{step}_fallback_rate": sum(
+                item["fallback_to_full"] for item in decisions
+                if item["denoise_step"] == step
+            ) / sum(item["denoise_step"] == step for item in decisions)
+            for step in (1, 2, 3)
+        }
+        rows.append({
+            "method": method,
+            "threshold_log_c1": threshold,
+            "fallback_rate": len(fallback) / len(decisions),
+            **by_step,
+            "mean_end_to_end_s": sum(elapsed) / len(elapsed),
+            **read_metrics(eval_name),
+        })
+    core_vbench = json.loads(
+        (DATASET / "vbench/validation25_core8/summary.json").read_text()
+    )["groups"]
+    threshold_vbench = json.loads(
+        (DATASET / "vbench/validation25_c1_thresholds/summary.json").read_text()
+    )["groups"]
+    vbench_groups = {
+        "FFFF": core_vbench["full_ffff"]["mean"],
+        "FPPF": core_vbench["stage1_fppf"]["mean"],
+        "FPPP": core_vbench["stage1_fppp"]["mean"],
+        "C1-r10": threshold_vbench["c1_r10"]["mean"],
+        "C1-r25": threshold_vbench["c1_r25"]["mean"],
+        "C1-r33": threshold_vbench["c1_r33"]["mean"],
+        "C1-r50": threshold_vbench["c1_r50"]["mean"],
+    }
+    for row in rows:
+        scores = vbench_groups[row["method"]]
+        row.update({f"vbench_{name}": scores[name] for name in VBENCH_DIMENSIONS})
+        row["vbench_core5_mean"] = sum(scores[name] for name in VBENCH_CORE5) / len(VBENCH_CORE5)
+    by_method = {row["method"]: row for row in rows}
+    comparison_metrics = (
+        "psnr_db", "ssim", "lpips_alex", "pixel_mse", "temporal_delta_mse",
+        *[f"vbench_{name}" for name in VBENCH_DIMENSIONS], "vbench_core5_mean",
+    )
+    comparisons = {}
+    for candidate in ("C1-r33", "C1-r50"):
+        comparisons[f"{candidate}_vs_FPPF"] = {
+            name: by_method[candidate][name] - by_method["FPPF"][name]
+            for name in comparison_metrics
+        }
+    OUTPUT.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "protocol": "validation25, seed 0, Stage-1 v4 FP32-master step 2000",
+        "rows": rows,
+        "comparisons": comparisons,
+    }
+    (OUTPUT / "summary.json").write_text(json.dumps(payload, indent=2, allow_nan=True) + "\n")
+    columns = [
+        "method", "threshold_log_c1", "fallback_rate", "p1_fallback_rate",
+        "p2_fallback_rate", "p3_fallback_rate", "mean_end_to_end_s", *METRICS,
+        *[f"vbench_{name}" for name in VBENCH_DIMENSIONS], "vbench_core5_mean",
+    ]
+    lines = [",".join(columns)]
+    for row in rows:
+        lines.append(",".join(str(row.get(column, "")) for column in columns))
+    (OUTPUT / "summary.csv").write_text("\n".join(lines) + "\n")
+    reference_lines = [
+        "# C1 threshold validation25 comparison",
+        "",
+        "## Reference metrics against FFFF",
+        "",
+        "| Method | Fallback | P1/P2/P3 fallback | PSNR | SSIM | LPIPS | Pixel MSE | Temporal MSE |",
+        "| --- | ---: | --- | ---: | ---: | ---: | ---: | ---: |",
+    ]
+    for row in rows:
+        routing = "-" if "p1_fallback_rate" not in row else "/".join(
+            f"{100 * row[f'p{step}_fallback_rate']:.1f}%" for step in (1, 2, 3)
+        )
+        psnr = "∞" if row["psnr_db"] == float("inf") else f"{row['psnr_db']:.4f}"
+        reference_lines.append(
+            f"| {row['method']} | {100 * row['fallback_rate']:.1f}% | {routing} | "
+            f"{psnr} | {row['ssim']:.5f} | {row['lpips_alex']:.5f} | "
+            f"{row['pixel_mse']:.6f} | {row['temporal_delta_mse']:.6f} |"
+        )
+    reference_lines.extend([
+        "", "## VBench", "",
+        "| Method | Subject | Background | Flicker | Motion | Dynamic | Aesthetic | Imaging | Overall | Core5 mean |",
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ])
+    for row in rows:
+        values = " | ".join(
+            f"{row[f'vbench_{name}']:.6f}" for name in VBENCH_DIMENSIONS
+        )
+        reference_lines.append(
+            f"| {row['method']} | {values} | {row['vbench_core5_mean']:.6f} |"
+        )
+    (OUTPUT / "report.md").write_text("\n".join(reference_lines) + "\n")
+    print(json.dumps(payload, indent=2, allow_nan=True))
+
+
+if __name__ == "__main__":
+    main()

tools/summarize_predictor_timestep_rollout_overfit8.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Summarize the six FPPP/FPPF evaluations from the replay sweep."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+SCHEDULES = ("fppp", "fppf")
+METRICS = (
+    "psnr_db", "frame_psnr_mean_db", "ssim", "lpips_alex",
+    "pixel_mse", "pixel_rmse", "pixel_mae", "temporal_delta_mse",
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--eval_parent", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument(
+        "--experiment",
+        default="v4 timestep-only FPPP rollout overfit8, 200 optimizer steps",
+    )
+    parser.add_argument(
+        "--variants",
+        default="replay0:0.0 replay0p2:0.2 replay0p4:0.4",
+    )
+    args = parser.parse_args()
+    variants = tuple(
+        (spec.split(":", 1)[0], float(spec.split(":", 1)[1]))
+        for spec in args.variants.split()
+    )
+    rows = []
+    for label, replay_weight in variants:
+        for schedule in SCHEDULES:
+            path = args.eval_parent / f"{label}_{schedule}" / "metrics.json"
+            with path.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+            summary = payload["summary_mean"]["predictor"]
+            rows.append(
+                {
+                    "variant": label,
+                    "replay_weight": replay_weight,
+                    "evaluation_schedule": schedule.upper(),
+                    "replace_steps": payload["config"]["replace_steps"],
+                    "videos": payload["config"]["videos_per_mode"],
+                    **{name: summary[name] for name in METRICS},
+                    "metrics_path": str(path),
+                }
+            )
+    result = {
+        "experiment": args.experiment,
+        "training_variants": [
+            {"variant": label, "replay_weight": weight} for label, weight in variants
+        ],
+        "evaluations_per_variant": ["FPPP", "FPPF"],
+        "videos_per_evaluation": 32,
+        "rows": rows,
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(
+        json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

tools/summarize_vbench_validation25_chunk_timestep_step2000.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Summarize VBench results for chunk+timestep step-2000 FPPF/FPPP videos."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+from collections import defaultdict
+from pathlib import Path
+from statistics import fmean
+
+
+DIMENSIONS = [
+    "subject_consistency",
+    "background_consistency",
+    "temporal_flickering",
+    "motion_smoothness",
+    "dynamic_degree",
+    "aesthetic_quality",
+    "imaging_quality",
+    "overall_consistency",
+]
+
+GROUP_ORDER = [
+    "chunk_timestep_step2000_fppf",
+    "chunk_timestep_step2000_fppp",
+]
+
+ACTION_RE = re.compile(r"_action_(\d{2})$")
+
+
+def load_dimension_result(run_root: Path, dimension: str) -> dict:
+    candidates = sorted((run_root / "raw" / dimension).glob("*_eval_results.json"))
+    if len(candidates) != 1:
+        raise RuntimeError(
+            f"Expected exactly one result JSON for {dimension}, got {len(candidates)}"
+        )
+    payload = json.loads(candidates[0].read_text())
+    if dimension not in payload:
+        raise KeyError(f"{dimension} missing from {candidates[0]}")
+    overall, records = payload[dimension]
+    if len(records) != 200:
+        raise RuntimeError(f"{dimension}: expected 200 records, got {len(records)}")
+    return {
+        "source": str(candidates[0]),
+        "official_overall": float(overall),
+        "records": records,
+    }
+
+
+def normalize_score(dimension: str, value: float) -> float:
+    if dimension == "imaging_quality":
+        return float(value) / 100.0
+    return float(value)
+
+
+def parse_record(record: dict, dimension: str) -> dict:
+    video_path = Path(record["video_path"])
+    stem = video_path.stem
+    if "__" not in stem:
+        raise ValueError(f"Missing group prefix in staged video name: {video_path}")
+    group, original_stem = stem.split("__", 1)
+    if group not in GROUP_ORDER:
+        raise ValueError(f"Unknown VBench group {group}: {video_path}")
+    action_match = ACTION_RE.search(original_stem)
+    if action_match is None:
+        raise ValueError(f"Cannot parse action id from {video_path}")
+    return {
+        "group": group,
+        "video_id": original_stem,
+        "action_id": int(action_match.group(1)),
+        "video_path": str(video_path),
+        "score": normalize_score(dimension, record["video_results"]),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run_root", type=Path, required=True)
+    args = parser.parse_args()
+    run_root = args.run_root.resolve()
+
+    parsed_by_dimension: dict[str, list[dict]] = {}
+    official_overall: dict[str, float] = {}
+    sources: dict[str, str] = {}
+    for dimension in DIMENSIONS:
+        result = load_dimension_result(run_root, dimension)
+        parsed_by_dimension[dimension] = [
+            parse_record(record, dimension) for record in result["records"]
+        ]
+        official_overall[dimension] = result["official_overall"]
+        sources[dimension] = result["source"]
+
+    per_video: dict[str, dict[str, dict]] = defaultdict(dict)
+    for dimension, records in parsed_by_dimension.items():
+        counts = defaultdict(int)
+        for record in records:
+            counts[record["group"]] += 1
+            item = per_video[record["group"]].setdefault(
+                record["video_id"],
+                {
+                    "action_id": record["action_id"],
+                    "video_id": record["video_id"],
+                    "scores": {},
+                },
+            )
+            item["scores"][dimension] = record["score"]
+        for group in GROUP_ORDER:
+            if counts[group] != 100:
+                raise RuntimeError(
+                    f"{dimension}/{group}: expected 100 records, got {counts[group]}"
+                )
+
+    group_summary = {}
+    for group in GROUP_ORDER:
+        items = list(per_video[group].values())
+        if len(items) != 100:
+            raise RuntimeError(f"{group}: expected 100 paired videos, got {len(items)}")
+        mean = {
+            dimension: fmean(item["scores"][dimension] for item in items)
+            for dimension in DIMENSIONS
+        }
+        mean_by_action_id = {}
+        for action_id in range(4):
+            action_items = [item for item in items if item["action_id"] == action_id]
+            if len(action_items) != 25:
+                raise RuntimeError(
+                    f"{group}/action{action_id}: expected 25 videos, "
+                    f"got {len(action_items)}"
+                )
+            mean_by_action_id[str(action_id)] = {
+                dimension: fmean(
+                    item["scores"][dimension] for item in action_items
+                )
+                for dimension in DIMENSIONS
+            }
+        group_summary[group] = {
+            "record_count": len(items),
+            "mean": mean,
+            "mean_by_action_id": mean_by_action_id,
+        }
+
+    payload = {
+        "dimensions": DIMENSIONS,
+        "group_order": GROUP_ORDER,
+        "official_overall_all_200_videos": official_overall,
+        "raw_sources": sources,
+        "groups": group_summary,
+    }
+    (run_root / "summary.json").write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n"
+    )
+
+    with (run_root / "summary.csv").open("w", newline="") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(["group", "video_count", *DIMENSIONS])
+        for group in GROUP_ORDER:
+            writer.writerow(
+                [
+                    group,
+                    group_summary[group]["record_count"],
+                    *[
+                        f"{group_summary[group]['mean'][dimension]:.8f}"
+                        for dimension in DIMENSIONS
+                    ],
+                ]
+            )
+
+    header = (
+        "| 版本 | 视频数 | Subject ↑ | Background ↑ | Flickering ↑ | "
+        "Motion smoothness ↑ | Dynamic degree ↑ | Aesthetic ↑ | Imaging ↑ | "
+        "Overall consistency ↑ |"
+    )
+    divider = (
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |"
+    )
+    rows = [header, divider]
+    for group in GROUP_ORDER:
+        mean = group_summary[group]["mean"]
+        rows.append(
+            "| "
+            + " | ".join(
+                [
+                    group,
+                    str(group_summary[group]["record_count"]),
+                    f"{mean['subject_consistency']:.6f}",
+                    f"{mean['background_consistency']:.6f}",
+                    f"{mean['temporal_flickering']:.6f}",
+                    f"{mean['motion_smoothness']:.6f}",
+                    f"{mean['dynamic_degree']:.6f}",
+                    f"{mean['aesthetic_quality']:.6f}",
+                    f"{mean['imaging_quality']:.6f}",
+                    f"{mean['overall_consistency']:.6f}",
+                ]
+            )
+            + " |"
+        )
+    (run_root / "summary.md").write_text("\n".join(rows) + "\n")
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

tools/summarize_vbench_validation25_core.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Summarize the five VBench metrics for the validation25 core comparison."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+from collections import defaultdict
+from pathlib import Path
+from statistics import fmean
+
+
+DIMENSIONS = [
+    "subject_consistency",
+    "background_consistency",
+    "temporal_flickering",
+    "motion_smoothness",
+    "dynamic_degree",
+    "aesthetic_quality",
+    "imaging_quality",
+    "overall_consistency",
+]
+
+GROUP_ORDER = [
+    "full_ffff",
+    "reuse_frrf",
+    "stage1_fppf",
+    "stage1_fppp",
+    "timestep_onpolicy_fppf",
+    "timestep_onpolicy_fppp",
+    "chunk_timestep_fppf",
+    "chunk_timestep_fppp",
+]
+
+COMPARISONS = [
+    ("timestep_onpolicy_fppf", "stage1_fppf"),
+    ("timestep_onpolicy_fppp", "stage1_fppp"),
+    ("chunk_timestep_fppf", "stage1_fppf"),
+    ("chunk_timestep_fppp", "stage1_fppp"),
+]
+
+ACTION_RE = re.compile(r"_action_(\d{2})$")
+
+
+def load_dimension_result(run_root: Path, dimension: str) -> dict:
+    candidates = sorted((run_root / "raw" / dimension).glob("*_eval_results.json"))
+    if len(candidates) != 1:
+        raise RuntimeError(
+            f"Expected exactly one result JSON for {dimension}, got {len(candidates)}"
+        )
+    payload = json.loads(candidates[0].read_text())
+    if dimension not in payload:
+        raise KeyError(f"{dimension} missing from {candidates[0]}")
+    overall, records = payload[dimension]
+    if len(records) != 800:
+        raise RuntimeError(f"{dimension}: expected 800 records, got {len(records)}")
+    return {
+        "source": str(candidates[0]),
+        "official_overall": float(overall),
+        "records": records,
+    }
+
+
+def normalize_score(dimension: str, value: float) -> float:
+    # VBench stores per-video MUSIQ scores on the 0..100 scale but divides its
+    # aggregate imaging_quality result by 100.
+    if dimension == "imaging_quality":
+        return float(value) / 100.0
+    return float(value)
+
+
+def parse_record(record: dict, dimension: str) -> dict:
+    video_path = Path(record["video_path"])
+    stem = video_path.stem
+    if "__" not in stem:
+        raise ValueError(f"Missing group prefix in staged video name: {video_path}")
+    group, original_stem = stem.split("__", 1)
+    if group not in GROUP_ORDER:
+        raise ValueError(f"Unknown VBench group {group}: {video_path}")
+    action_match = ACTION_RE.search(original_stem)
+    if action_match is None:
+        raise ValueError(f"Cannot parse action id from {video_path}")
+    return {
+        "group": group,
+        "video_id": original_stem,
+        "action_id": int(action_match.group(1)),
+        "video_path": str(video_path),
+        "score": normalize_score(dimension, record["video_results"]),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run_root", type=Path, required=True)
+    args = parser.parse_args()
+    run_root = args.run_root.resolve()
+
+    parsed_by_dimension: dict[str, list[dict]] = {}
+    official_overall: dict[str, float] = {}
+    sources: dict[str, str] = {}
+    for dimension in DIMENSIONS:
+        result = load_dimension_result(run_root, dimension)
+        parsed = [parse_record(record, dimension) for record in result["records"]]
+        parsed_by_dimension[dimension] = parsed
+        official_overall[dimension] = result["official_overall"]
+        sources[dimension] = result["source"]
+
+    per_video: dict[str, dict[str, dict]] = defaultdict(dict)
+    for dimension, records in parsed_by_dimension.items():
+        counts = defaultdict(int)
+        for record in records:
+            counts[record["group"]] += 1
+            item = per_video[record["group"]].setdefault(
+                record["video_id"],
+                {
+                    "action_id": record["action_id"],
+                    "video_id": record["video_id"],
+                    "scores": {},
+                },
+            )
+            item["scores"][dimension] = record["score"]
+        for group in GROUP_ORDER:
+            if counts[group] != 100:
+                raise RuntimeError(
+                    f"{dimension}/{group}: expected 100 records, got {counts[group]}"
+                )
+
+    group_summary = {}
+    for group in GROUP_ORDER:
+        items = list(per_video[group].values())
+        if len(items) != 100:
+            raise RuntimeError(f"{group}: expected 100 paired videos, got {len(items)}")
+        mean = {
+            dimension: fmean(item["scores"][dimension] for item in items)
+            for dimension in DIMENSIONS
+        }
+        mean_by_action_id = {}
+        for action_id in range(4):
+            action_items = [item for item in items if item["action_id"] == action_id]
+            if len(action_items) != 25:
+                raise RuntimeError(
+                    f"{group}/action{action_id}: expected 25 videos, got {len(action_items)}"
+                )
+            mean_by_action_id[str(action_id)] = {
+                dimension: fmean(
+                    item["scores"][dimension] for item in action_items
+                )
+                for dimension in DIMENSIONS
+            }
+        group_summary[group] = {
+            "record_count": len(items),
+            "mean": mean,
+            "mean_by_action_id": mean_by_action_id,
+        }
+
+    comparisons = {}
+    for candidate, baseline in COMPARISONS:
+        candidate_items = per_video[candidate]
+        baseline_items = per_video[baseline]
+        if set(candidate_items) != set(baseline_items):
+            raise RuntimeError(f"Pairing mismatch: {candidate} vs {baseline}")
+        key = f"{candidate}_vs_{baseline}"
+        comparisons[key] = {
+            "candidate": candidate,
+            "baseline": baseline,
+            "delta": {},
+            "wins_out_of_100": {},
+        }
+        for dimension in DIMENSIONS:
+            deltas = [
+                candidate_items[video_id]["scores"][dimension]
+                - baseline_items[video_id]["scores"][dimension]
+                for video_id in sorted(candidate_items)
+            ]
+            comparisons[key]["delta"][dimension] = fmean(deltas)
+            comparisons[key]["wins_out_of_100"][dimension] = sum(
+                delta > 0 for delta in deltas
+            )
+
+    payload = {
+        "dimensions": DIMENSIONS,
+        "group_order": GROUP_ORDER,
+        "official_overall_all_800_videos": official_overall,
+        "raw_sources": sources,
+        "groups": group_summary,
+        "comparisons": comparisons,
+    }
+    (run_root / "summary.json").write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n"
+    )
+
+    with (run_root / "summary.csv").open("w", newline="") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(["group", "video_count", *DIMENSIONS])
+        for group in GROUP_ORDER:
+            writer.writerow(
+                [
+                    group,
+                    group_summary[group]["record_count"],
+                    *[
+                        f"{group_summary[group]['mean'][dimension]:.8f}"
+                        for dimension in DIMENSIONS
+                    ],
+                ]
+            )
+
+    header = (
+        "| 版本 | 视频数 | Subject ↑ | Background ↑ | Flickering ↑ | "
+        "Motion smoothness ↑ | Dynamic degree ↑ | Aesthetic ↑ | Imaging ↑ | "
+        "Overall consistency ↑ |"
+    )
+    divider = (
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |"
+    )
+    rows = [header, divider]
+    for group in GROUP_ORDER:
+        mean = group_summary[group]["mean"]
+        rows.append(
+            "| "
+            + " | ".join(
+                [
+                    group,
+                    str(group_summary[group]["record_count"]),
+                    f"{mean['subject_consistency']:.6f}",
+                    f"{mean['background_consistency']:.6f}",
+                    f"{mean['temporal_flickering']:.6f}",
+                    f"{mean['motion_smoothness']:.6f}",
+                    f"{mean['dynamic_degree']:.6f}",
+                    f"{mean['aesthetic_quality']:.6f}",
+                    f"{mean['imaging_quality']:.6f}",
+                    f"{mean['overall_consistency']:.6f}",
+                ]
+            )
+            + " |"
+        )
+    (run_root / "summary.md").write_text("\n".join(rows) + "\n")
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

tools/summarize_vbench_validation25_pair.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Summarize eight VBench dimensions for validation25 video groups."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+from collections import defaultdict
+from pathlib import Path
+from statistics import fmean
+
+
+DIMENSIONS = [
+    "subject_consistency",
+    "background_consistency",
+    "temporal_flickering",
+    "motion_smoothness",
+    "dynamic_degree",
+    "aesthetic_quality",
+    "imaging_quality",
+    "overall_consistency",
+]
+
+ACTION_RE = re.compile(r"_action_(\d{2})$")
+
+
+def load_dimension_result(
+    run_root: Path, dimension: str, expected_records: int
+) -> dict:
+    candidates = sorted((run_root / "raw" / dimension).glob("*_eval_results.json"))
+    if len(candidates) != 1:
+        raise RuntimeError(
+            f"Expected exactly one result JSON for {dimension}, got {len(candidates)}"
+        )
+    payload = json.loads(candidates[0].read_text())
+    if dimension not in payload:
+        raise KeyError(f"{dimension} missing from {candidates[0]}")
+    overall, records = payload[dimension]
+    if len(records) != expected_records:
+        raise RuntimeError(
+            f"{dimension}: expected {expected_records} records, got {len(records)}"
+        )
+    return {
+        "source": str(candidates[0]),
+        "official_overall": float(overall),
+        "records": records,
+    }
+
+
+def normalize_score(dimension: str, value: float) -> float:
+    if dimension == "imaging_quality":
+        return float(value) / 100.0
+    return float(value)
+
+
+def parse_record(record: dict, dimension: str, group_order: list[str]) -> dict:
+    video_path = Path(record["video_path"])
+    stem = video_path.stem
+    if "__" not in stem:
+        raise ValueError(f"Missing group prefix in staged video name: {video_path}")
+    group, original_stem = stem.split("__", 1)
+    if group not in group_order:
+        raise ValueError(f"Unknown VBench group {group}: {video_path}")
+    action_match = ACTION_RE.search(original_stem)
+    if action_match is None:
+        raise ValueError(f"Cannot parse action id from {video_path}")
+    return {
+        "group": group,
+        "video_id": original_stem,
+        "action_id": int(action_match.group(1)),
+        "video_path": str(video_path),
+        "score": normalize_score(dimension, record["video_results"]),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run_root", type=Path, required=True)
+    parser.add_argument("--group", action="append", required=True)
+    parser.add_argument("--videos_per_group", type=int, default=100)
+    args = parser.parse_args()
+    run_root = args.run_root.resolve()
+    group_order = list(args.group)
+    if not group_order or len(set(group_order)) != len(group_order):
+        raise ValueError("Pass one or more distinct --group values")
+    expected_records = len(group_order) * args.videos_per_group
+
+    parsed_by_dimension: dict[str, list[dict]] = {}
+    official_overall: dict[str, float] = {}
+    sources: dict[str, str] = {}
+    for dimension in DIMENSIONS:
+        result = load_dimension_result(run_root, dimension, expected_records)
+        parsed_by_dimension[dimension] = [
+            parse_record(record, dimension, group_order)
+            for record in result["records"]
+        ]
+        official_overall[dimension] = result["official_overall"]
+        sources[dimension] = result["source"]
+
+    per_video: dict[str, dict[str, dict]] = defaultdict(dict)
+    for dimension, records in parsed_by_dimension.items():
+        counts = defaultdict(int)
+        for record in records:
+            counts[record["group"]] += 1
+            item = per_video[record["group"]].setdefault(
+                record["video_id"],
+                {
+                    "action_id": record["action_id"],
+                    "video_id": record["video_id"],
+                    "scores": {},
+                },
+            )
+            item["scores"][dimension] = record["score"]
+        for group in group_order:
+            if counts[group] != args.videos_per_group:
+                raise RuntimeError(
+                    f"{dimension}/{group}: expected {args.videos_per_group} "
+                    f"records, got {counts[group]}"
+                )
+
+    group_summary = {}
+    for group in group_order:
+        items = list(per_video[group].values())
+        if len(items) != args.videos_per_group:
+            raise RuntimeError(
+                f"{group}: expected {args.videos_per_group} videos, got {len(items)}"
+            )
+        mean = {
+            dimension: fmean(item["scores"][dimension] for item in items)
+            for dimension in DIMENSIONS
+        }
+        mean_by_action_id = {}
+        for action_id in range(4):
+            action_items = [item for item in items if item["action_id"] == action_id]
+            if len(action_items) * 4 != args.videos_per_group:
+                raise RuntimeError(
+                    f"{group}/action{action_id}: uneven validation action count "
+                    f"{len(action_items)}"
+                )
+            mean_by_action_id[str(action_id)] = {
+                dimension: fmean(item["scores"][dimension] for item in action_items)
+                for dimension in DIMENSIONS
+            }
+        group_summary[group] = {
+            "record_count": len(items),
+            "mean": mean,
+            "mean_by_action_id": mean_by_action_id,
+        }
+
+    summary = {
+        "dimensions": DIMENSIONS,
+        "group_order": group_order,
+        "official_overall_all_videos": official_overall,
+        "raw_sources": sources,
+        "groups": group_summary,
+    }
+    (run_root / "summary.json").write_text(
+        json.dumps(summary, indent=2, sort_keys=True) + "\n"
+    )
+
+    with (run_root / "summary.csv").open("w", newline="") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(["group", "video_count", *DIMENSIONS])
+        for group in group_order:
+            writer.writerow(
+                [
+                    group,
+                    group_summary[group]["record_count"],
+                    *[
+                        f"{group_summary[group]['mean'][dimension]:.8f}"
+                        for dimension in DIMENSIONS
+                    ],
+                ]
+            )
+
+    rows = [
+        (
+            "| 版本 | 视频数 | Subject ↑ | Background ↑ | Flickering ↑ | "
+            "Motion smoothness ↑ | Dynamic degree ↑ | Aesthetic ↑ | Imaging ↑ | "
+            "Overall consistency ↑ |"
+        ),
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ]
+    for group in group_order:
+        mean = group_summary[group]["mean"]
+        rows.append(
+            "| "
+            + " | ".join(
+                [
+                    group,
+                    str(group_summary[group]["record_count"]),
+                    f"{mean['subject_consistency']:.6f}",
+                    f"{mean['background_consistency']:.6f}",
+                    f"{mean['temporal_flickering']:.6f}",
+                    f"{mean['motion_smoothness']:.6f}",
+                    f"{mean['dynamic_degree']:.6f}",
+                    f"{mean['aesthetic_quality']:.6f}",
+                    f"{mean['imaging_quality']:.6f}",
+                    f"{mean['overall_consistency']:.6f}",
+                ]
+            )
+            + " |"
+        )
+    (run_root / "summary.md").write_text("\n".join(rows) + "\n")
+    print(json.dumps(summary, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

tools/supervise_predictor_v4_fp32master_training.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+output_dir="${repo_root}/checkpoints/predictor_v4_prefeature_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab"
+final_weights="${output_dir}/predictor_step_02000.safetensors"
+resume_path="${output_dir}/training_latest.pt"
+lock_path="${output_dir}/supervisor.lock"
+mkdir -p "${output_dir}"
+
+exec 9>"${lock_path}"
+if ! flock -n 9; then
+  echo "[supervisor] another FP32-master v4 supervisor is already active"
+  exit 0
+fi
+
+while [[ ! -f "${final_weights}" ]]; do
+  if pgrep -f "python -u ${repo_root}/train_predictor_v4.py .*--output_dir ${output_dir}" >/dev/null; then
+    sleep 60
+    continue
+  fi
+
+  echo "[supervisor] FP32-master v4 worker is absent; restarting at $(date -u +%FT%TZ)"
+  if [[ -f "${resume_path}" ]]; then
+    bash "${repo_root}/tools/launch_predictor_v4_fp32master_training.sh" \
+      "${output_dir}" "${resume_path}" || true
+  else
+    bash "${repo_root}/tools/launch_predictor_v4_fp32master_training.sh" \
+      "${output_dir}" || true
+  fi
+  sleep 30
+done
+
+echo "[supervisor] step 2000 checkpoint is complete: ${final_weights}"

tools/supervise_predictor_v4_rollout_fppf_overfit8_training.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+output_dir="${repo_root}/checkpoints/predictor_v4_rollout_fppf_blocks1-52_overfit8_seed20260721_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps300_swarmup8_bwarmup8_swanlab"
+final_weights="${output_dir}/predictor_step_00300.safetensors"
+resume_path="${output_dir}/training_latest.pt"
+lock_path="${output_dir}/supervisor.lock"
+mkdir -p "${output_dir}"
+
+exec 9>"${lock_path}"
+if ! flock -n 9; then
+  echo "[supervisor] another FPPF rollout overfit supervisor is already active"
+  exit 0
+fi
+
+while [[ ! -f "${final_weights}" ]]; do
+  if pgrep -f "train_predictor_v4_rollout.py .*--output_dir ${output_dir} .*--rollout_schedule fppf" >/dev/null; then
+    sleep 60
+    continue
+  fi
+
+  echo "[supervisor] FPPF rollout worker is absent; restarting at $(date -u +%FT%TZ)"
+  if [[ -f "${resume_path}" ]]; then
+    bash "${repo_root}/tools/launch_predictor_v4_rollout_fppf_overfit8_training.sh" \
+      "${output_dir}" "${resume_path}" 300 || true
+  else
+    bash "${repo_root}/tools/launch_predictor_v4_rollout_fppf_overfit8_training.sh" \
+      "${output_dir}" "" 300 || true
+  fi
+  sleep 30
+done
+
+echo "[supervisor] FPPF step 300 checkpoint is complete: ${final_weights}"

tools/supervise_predictor_v4_rollout_overfit8_training.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+output_dir="${repo_root}/checkpoints/predictor_v4_rollout_fppp_blocks1-52_overfit8_seed20260721_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup8_bwarmup8_swanlab"
+final_weights="${output_dir}/predictor_step_02000.safetensors"
+resume_path="${output_dir}/training_latest.pt"
+lock_path="${output_dir}/supervisor.lock"
+mkdir -p "${output_dir}"
+
+exec 9>"${lock_path}"
+if ! flock -n 9; then
+  echo "[supervisor] another rollout overfit supervisor is already active"
+  exit 0
+fi
+
+while [[ ! -f "${final_weights}" ]]; do
+  if pgrep -f "python -u ${repo_root}/train_predictor_v4_rollout.py .*--output_dir ${output_dir}" >/dev/null; then
+    sleep 60
+    continue
+  fi
+
+  echo "[supervisor] rollout overfit worker is absent; restarting at $(date -u +%FT%TZ)"
+  if [[ -f "${resume_path}" ]]; then
+    bash "${repo_root}/tools/launch_predictor_v4_rollout_overfit8_training.sh" \
+      "${output_dir}" "${resume_path}" || true
+  else
+    bash "${repo_root}/tools/launch_predictor_v4_rollout_overfit8_training.sh" \
+      "${output_dir}" || true
+  fi
+  sleep 30
+done
+
+echo "[supervisor] step 2000 checkpoint is complete: ${final_weights}"

tools/supervise_predictor_v4_rollout_training.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+output_dir="${repo_root}/checkpoints/predictor_v4_rollout_fppp_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab"
+final_weights="${output_dir}/predictor_step_02000.safetensors"
+resume_path="${output_dir}/training_latest.pt"
+lock_path="${output_dir}/supervisor.lock"
+mkdir -p "${output_dir}"
+
+exec 9>"${lock_path}"
+if ! flock -n 9; then
+  echo "[supervisor] another rollout supervisor is already active"
+  exit 0
+fi
+
+while [[ ! -f "${final_weights}" ]]; do
+  if pgrep -f "python -u ${repo_root}/train_predictor_v4_rollout.py .*--output_dir ${output_dir}" >/dev/null; then
+    sleep 60
+    continue
+  fi
+
+  echo "[supervisor] rollout worker is absent; restarting at $(date -u +%FT%TZ)"
+  if [[ -f "${resume_path}" ]]; then
+    bash "${repo_root}/tools/launch_predictor_v4_rollout_training.sh" \
+      "${output_dir}" "${resume_path}" || true
+  else
+    bash "${repo_root}/tools/launch_predictor_v4_rollout_training.sh" \
+      "${output_dir}" || true
+  fi
+  sleep 30
+done
+
+echo "[supervisor] step 2000 checkpoint is complete: ${final_weights}"

tools/supervise_previous_vbench_validation_predictors.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor"
+dataset_root="${PREDICTOR_HOLDOUT_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/hyworldplay_predictor_vbench_val25_test50}"
+eval_base="${dataset_root}/evaluations"
+lock_path="${eval_base}/previous_versions_validation.lock"
+complete_path="${eval_base}/previous_versions_validation.completed"
+mkdir -p "${eval_base}"
+
+exec 9>"${lock_path}"
+if ! flock -n 9; then
+  echo "[supervisor] another previous-version validation supervisor is active"
+  exit 0
+fi
+
+run_until_complete() {
+  local eval_name="$1"
+  local weights="$2"
+  local source_blocks="$3"
+  local predictor_variant="$4"
+  local marker="${eval_base}/${eval_name}/sync.completed"
+  while [[ ! -f "${marker}" ]]; do
+    echo "[supervisor] starting ${eval_name} at $(date -u +%FT%TZ)"
+    if ! bash "${repo_root}/tools/launch_vbench_validation_predictor.sh" \
+      "${eval_name}" "${weights}" "${source_blocks}" "${predictor_variant}"; then
+      echo "[supervisor] ${eval_name} failed; retrying in 30 seconds"
+      sleep 30
+    fi
+  done
+  echo "[supervisor] completed ${eval_name} at $(date -u +%FT%TZ)"
+}
+
+run_until_complete \
+  eval_validation25_v4_blocks0-53_bf16_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100 \
+  "${repo_root}/checkpoints/predictor_v4_prefeature_blocks0-53_bf16_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors" \
+  0,53 v4
+
+run_until_complete \
+  eval_validation25_v4_blocks1-52_bf16_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100 \
+  "${repo_root}/checkpoints/predictor_v4_prefeature_blocks1-52_bf16_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors" \
+  1,52 v4
+
+run_until_complete \
+  eval_validation25_disca_blocks0-53_bf16_ckptstep2000_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100 \
+  "${repo_root}/checkpoints/predictor_disca_blocks0-53_bf16_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/predictor_step_02000.safetensors" \
+  0,53 disca
+
+date -u +%FT%TZ >"${complete_path}"
+echo "[supervisor] all previous-version validation evaluations are complete"

tools/supervise_training_tests_then_helios.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+ROOT=/data3/chenzhuo/workspace/HY-WorldPlay-DEV-Predictor
+HELIOS=/data3/chenzhuo/workspace/Helios
+PYTHON=/data3/chenzhuo/anaconda3/envs/worldplay/bin/python
+SUPERVISOR_LOG="$ROOT/outputs/supervise_training_tests_then_helios.log"
+
+V2_TRAIN_PID=4073736
+V3_TRAIN_PID=3092818
+V2_WEIGHTS="$ROOT/checkpoints/predictor_v2_1_52/predictor_step_02000.safetensors"
+V3_WEIGHTS="$ROOT/checkpoints/predictor_v3_0_53/predictor_step_02000.safetensors"
+
+log() {
+    printf '[%s] %s\n' "$(date '+%F %T')" "$*"
+}
+
+latest_step() {
+    local path=$1
+    if [[ -s "$path" ]]; then
+        tail -n 1 "$path" | sed -n 's/.*"global_step"[ ]*:[ ]*\([0-9]*\).*/\1/p'
+    else
+        printf '?'
+    fi
+}
+
+wait_for_training() {
+    local label=$1
+    local pid=$2
+    local train_log=$3
+    local weights=$4
+    while kill -0 "$pid" 2>/dev/null; do
+        log "$label is active: step=$(latest_step "$train_log")/2000 pid=$pid"
+        sleep 60
+    done
+    if [[ ! -s "$weights" ]]; then
+        log "ERROR: $label exited without final weights: $weights"
+        return 1
+    fi
+    log "$label completed and final weights exist: $weights"
+}
+
+validate_eval() {
+    local output_dir=$1
+    local expected_runs=$2
+    "$PYTHON" - "$output_dir" "$expected_runs" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+expected = int(sys.argv[2])
+payload = json.loads((root / "metrics.json").read_text())
+runs = payload.get("runs", [])
+if len(runs) != expected:
+    raise SystemExit(f"expected {expected} runs, found {len(runs)}")
+missing = [run.get("video_path") for run in runs if not Path(run["video_path"]).is_file()]
+if missing:
+    raise SystemExit(f"missing videos: {missing[:3]}")
+print(f"validated {len(runs)} runs and videos in {root}")
+PY
+}
+
+adopt_or_validate_eval() {
+    local label=$1
+    local output_dir=$2
+    local expected_runs=$3
+    if validate_eval "$output_dir" "$expected_runs" >/dev/null 2>&1; then
+        log "$label is already complete: $output_dir"
+        return 0
+    fi
+
+    local pid
+    pid=$(pgrep -f "eval_predictor_v2_rollout.py.*--output_dir $output_dir" | head -n 1 || true)
+    if [[ -z "$pid" ]]; then
+        return 1
+    fi
+    log "adopting active $label process: pid=$pid output=$output_dir"
+    while kill -0 "$pid" 2>/dev/null; do
+        log "$label is active: pid=$pid"
+        sleep 60
+    done
+    validate_eval "$output_dir" "$expected_runs" || return 1
+    log "$label completed: $output_dir"
+}
+
+run_v2_test_after_training() {
+    wait_for_training \
+        'v2 [1,52] GPU4 training' \
+        "$V2_TRAIN_PID" \
+        "$ROOT/checkpoints/predictor_v2_1_52/train_log.jsonl" \
+        "$V2_WEIGHTS" || return 1
+
+    local output_dir="$ROOT/outputs/predictor_v2/online_1_52_step2000"
+    local eval_log="$ROOT/outputs/predictor_v2_online_1_52_step2000.log"
+    if adopt_or_validate_eval 'v2 [1,52] test' "$output_dir" 30; then
+        return 0
+    fi
+    log "starting v2 [1,52] 10-case Full/Reuse/Predictor test on GPU4"
+    (
+        cd "$ROOT" || exit 1
+        unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
+        export CUDA_VISIBLE_DEVICES=4 PYTHONPATH=.
+        "$PYTHON" -u eval_predictor_v2_rollout.py \
+            --predictor_version v2 \
+            --weights_1_52 "$V2_WEIGHTS" \
+            --modes full,reuse,predictor_1_52 \
+            --case_ids 1-10 \
+            --video_frames 253 \
+            --output_dir "$output_dir"
+    ) >"$eval_log" 2>&1
+    local status=$?
+    if (( status != 0 )); then
+        log "ERROR: v2 [1,52] test failed with status $status; log=$eval_log"
+        return "$status"
+    fi
+    validate_eval "$output_dir" 30 || return 1
+    log "v2 [1,52] test completed: $output_dir"
+}
+
+run_v3_test_after_training() {
+    wait_for_training \
+        'v3 [0,53] GPU5 training' \
+        "$V3_TRAIN_PID" \
+        "$ROOT/checkpoints/predictor_v3_0_53/train_log.jsonl" \
+        "$V3_WEIGHTS" || return 1
+
+    local smoke_dir="$ROOT/outputs/predictor_v3/online_0_53_step2000_smoke"
+    local smoke_log="$ROOT/outputs/predictor_v3_online_0_53_step2000_smoke.log"
+    local status=0
+    if ! adopt_or_validate_eval 'v3 [0,53] smoke' "$smoke_dir" 2; then
+        log "starting v3 [0,53] two-chunk online smoke on GPU5"
+        (
+            cd "$ROOT" || exit 1
+            unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
+            export CUDA_VISIBLE_DEVICES=5 PYTHONPATH=.
+            "$PYTHON" -u eval_predictor_v2_rollout.py \
+                --predictor_version v3 \
+                --weights_0_53 "$V3_WEIGHTS" \
+                --modes full,predictor_0_53 \
+                --case_ids 1 \
+                --video_frames 29 \
+                --output_dir "$smoke_dir"
+        ) >"$smoke_log" 2>&1
+        status=$?
+        if (( status != 0 )); then
+            log "ERROR: v3 [0,53] smoke failed with status $status; log=$smoke_log"
+            return "$status"
+        fi
+        validate_eval "$smoke_dir" 2 || return 1
+    fi
+    log "v3 smoke passed; starting 10-case Full/Reuse/Predictor test on GPU5"
+
+    local output_dir="$ROOT/outputs/predictor_v3/online_0_53_step2000"
+    local eval_log="$ROOT/outputs/predictor_v3_online_0_53_step2000.log"
+    if adopt_or_validate_eval 'v3 [0,53] full test' "$output_dir" 30; then
+        return 0
+    fi
+    (
+        cd "$ROOT" || exit 1
+        unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
+        export CUDA_VISIBLE_DEVICES=5 PYTHONPATH=.
+        "$PYTHON" -u eval_predictor_v2_rollout.py \
+            --predictor_version v3 \
+            --weights_0_53 "$V3_WEIGHTS" \
+            --modes full,reuse,predictor_0_53 \
+            --case_ids 1-10 \
+            --video_frames 253 \
+            --output_dir "$output_dir"
+    ) >"$eval_log" 2>&1
+    status=$?
+    if (( status != 0 )); then
+        log "ERROR: v3 [0,53] test failed with status $status; log=$eval_log"
+        return "$status"
+    fi
+    validate_eval "$output_dir" 30 || return 1
+    log "v3 [0,53] test completed: $output_dir"
+}
+
+wait_for_existing_v2_0_53_test() {
+    local pid=1215665
+    local output_dir="$ROOT/outputs/predictor_v2/online_0_53_step2000"
+    while kill -0 "$pid" 2>/dev/null; do
+        log "v2 [0,53] GPU3 test is active: pid=$pid"
+        sleep 60
+    done
+    validate_eval "$output_dir" 30 || {
+        log "ERROR: v2 [0,53] GPU3 test did not complete successfully"
+        return 1
+    }
+    log "v2 [0,53] GPU3 test completed"
+}
+
+launch_helios() {
+    local gpu=$1
+    local stamp=$2
+    local output_root="$HELIOS/output_helios/moviebench_990_gpu${gpu}_post_predictor_${stamp}"
+    local helios_log="$HELIOS/logs/run_gpu${gpu}_post_predictor_${stamp}.log"
+    (
+        cd "$HELIOS" || exit 1
+        unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
+        export GPU="$gpu" OUTPUT_ROOT="$output_root"
+        exec bash "$HELIOS/run.sh"
+    ) >"$helios_log" 2>&1 < /dev/null &
+    local pid=$!
+    log "launched Helios/run.sh on GPU$gpu: pid=$pid log=$helios_log" >&2
+    printf '%s' "$pid"
+}
+
+main() {
+    mkdir -p "$ROOT/outputs" "$HELIOS/logs"
+    log "supervisor started"
+
+    run_v2_test_after_training &
+    local worker4=$!
+    run_v3_test_after_training &
+    local worker5=$!
+
+    wait "$worker4"
+    local status4=$?
+    wait "$worker5"
+    local status5=$?
+    wait_for_existing_v2_0_53_test
+    local status3=$?
+
+    if (( status3 != 0 || status4 != 0 || status5 != 0 )); then
+        log "ERROR: at least one required test failed; Helios will not be launched (gpu3=$status3 gpu4=$status4 gpu5=$status5)"
+        return 1
+    fi
+
+    local stamp
+    stamp=$(date '+%Y%m%d_%H%M%S')
+    local helios4 helios5
+    helios4=$(launch_helios 4 "$stamp")
+    helios5=$(launch_helios 5 "$stamp")
+    sleep 60
+    if ! kill -0 "$helios4" 2>/dev/null || ! kill -0 "$helios5" 2>/dev/null; then
+        log "ERROR: a Helios process exited during startup (gpu4=$helios4 gpu5=$helios5)"
+        return 1
+    fi
+    log "Helios processes are active on GPU4/GPU5; supervisor finished successfully"
+}
+
+main >>"$SUPERVISOR_LOG" 2>&1

tools/sync_predictor_prefeature_to_s3.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export BUCKET="${BUCKET:-s3-us-west2-default}"
+export FS_ID="${FS_ID:-fs-05c60be7352499179}"
+export MOUNT_POINT="${MOUNT_POINT:-/mnt/s3files/s3-us-west2-default}"
+
+dataset_name="hyworldplay_predictor_prefeature_v4"
+nvme_root="${PREDICTOR_DATA_NVME_ROOT:-/mnt/local_nvme/zoubin/cz/${dataset_name}}"
+s3_uri="${PREDICTOR_DATA_S3_URI:-s3://${BUCKET}/zoubin/cz/projects/HY-WorldPlay-DEV-Predictor/datasets/${dataset_name}}"
+
+[[ -f "${nvme_root}/manifest.jsonl" ]] || {
+  echo "ERROR: missing merged manifest in ${nvme_root}" >&2
+  exit 1
+}
+[[ $(wc -l < "${nvme_root}/manifest.jsonl") -eq 3200 ]] || {
+  echo "ERROR: manifest.jsonl must contain 3200 records" >&2
+  exit 1
+}
+[[ $(wc -l < "${nvme_root}/train_eval_manifest.jsonl") -eq 2800 ]] || {
+  echo "ERROR: train_eval_manifest.jsonl must contain 2800 records" >&2
+  exit 1
+}
+[[ $(find "${nvme_root}/cases" -type f -name '*.safetensors' | wc -l) -eq 100 ]] || {
+  echo "ERROR: expected 100 case tensor files" >&2
+  exit 1
+}
+[[ $(find "${nvme_root}/steps" -type f -name '*.safetensors' | wc -l) -eq 3200 ]] || {
+  echo "ERROR: expected 3200 step tensor files" >&2
+  exit 1
+}
+[[ $(find "${nvme_root}/context_prefeature" -type f -name '*.safetensors' | wc -l) -eq 12800 ]] || {
+  echo "ERROR: expected 12800 Context prefeature files" >&2
+  exit 1
+}
+[[ $(find "${nvme_root}/videos" -type f -name '*.mp4' | wc -l) -eq 400 ]] || {
+  echo "ERROR: expected 400 evaluation videos" >&2
+  exit 1
+}
+
+echo "[dataset] validated complete NVMe build: ${nvme_root}"
+echo "[dataset] syncing ${nvme_root} -> ${s3_uri}"
+aws s3 sync "${nvme_root}" "${s3_uri}" --only-show-errors
+echo "[dataset] durable S3 synchronization completed"

tools/train_evaluate_predictor_confidence.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""Train C0/C1/C2 confidence heads and report held-out risk coverage."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+import os
+import random
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+import torch.distributed as dist
+import torch.nn.functional as F
+from scipy.stats import pearsonr, spearmanr
+from torch.nn.parallel import DistributedDataParallel as DDP
+from torch.utils.data import DataLoader, TensorDataset
+from torch.utils.data.distributed import DistributedSampler
+
+from models.confidence_head import PredictorConfidenceHead
+
+
+TARGETS = ("c0", "c1", "c2")
+RATIOS = (0.0, 0.05, 0.1, 0.2, 0.25, 1 / 3, 0.4, 0.5, 0.6, 0.75, 1.0)
+
+
+def load_features(directory):
+    shards = [torch.load(path, map_location="cpu", weights_only=False) for path in sorted(directory.glob("features_rank_*.pt"))]
+    if not shards:
+        raise FileNotFoundError(f"No feature shards in {directory}")
+    names = ("pooled_hidden", "log_residual", "true_c0", "true_c1", "true_c2", "scheduler_coeff", "step_id")
+    result = {name: torch.cat([shard[name] for shard in shards]) for name in names}
+    result["metadata"] = sum((shard["metadata"] for shard in shards), [])
+    order = sorted(range(len(result["metadata"])), key=lambda i: tuple(result["metadata"][i][k] for k in ("case_id", "action_id", "chunk_id", "step_id")))
+    index = torch.tensor(order)
+    for name in names:
+        result[name] = result[name][index]
+    result["metadata"] = [result["metadata"][i] for i in order]
+    return result
+
+
+def train_head(
+    features, target_name, device, epochs, batch_size, seed, rank, world_size,
+    mlp_dims,
+):
+    torch.manual_seed(seed)
+    model = PredictorConfidenceHead(
+        features["pooled_hidden"].shape[1], mlp_dims=mlp_dims
+    ).to(device)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4, weight_decay=1e-4)
+    dataset = TensorDataset(
+        features["pooled_hidden"].float(), features["step_id"].long(),
+        features["log_residual"].float(),
+        torch.log(features[f"true_{target_name}"].float() + 1e-8),
+    )
+    sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank, shuffle=True, seed=seed) if world_size > 1 else None
+    loader = DataLoader(dataset, batch_size=batch_size, shuffle=sampler is None, sampler=sampler)
+    wrapped = DDP(model, device_ids=[device.index], broadcast_buffers=False) if world_size > 1 else model
+    wrapped.train()
+    for epoch in range(epochs):
+        if sampler is not None:
+            sampler.set_epoch(epoch)
+        total = count = 0
+        for pooled, step, residual, target in loader:
+            pooled, step, residual, target = (x.to(device) for x in (pooled, step, residual, target))
+            optimizer.zero_grad(set_to_none=True)
+            loss = F.smooth_l1_loss(wrapped(pooled, step, residual), target)
+            loss.backward()
+            optimizer.step()
+            total += float(loss.detach()) * len(pooled)
+            count += len(pooled)
+        if rank == 0 and (epoch == 0 or (epoch + 1) % 10 == 0):
+            print(f"{target_name} epoch {epoch + 1}/{epochs} loss={total / count:.6f}", flush=True)
+    if world_size > 1:
+        dist.barrier()
+    return model.eval()
+
+
+@torch.inference_mode()
+def predict(model, features, device):
+    result = []
+    for start in range(0, len(features["step_id"]), 512):
+        stop = start + 512
+        result.append(model(
+            features["pooled_hidden"][start:stop].float().to(device),
+            features["step_id"][start:stop].long().to(device),
+            features["log_residual"][start:stop].float().to(device),
+        ).cpu())
+    return torch.cat(result).numpy()
+
+
+def correlation(x, y, function):
+    if len(x) < 2 or np.all(x == x[0]) or np.all(y == y[0]):
+        return float("nan")
+    return float(function(x, y).statistic)
+
+
+def metric_rows(split, predictions, features):
+    rows = []
+    steps = features["step_id"].numpy()
+    for target, score in predictions.items():
+        truth = np.log(features[f"true_{target}"].numpy() + 1e-8)
+        groups = [("overall", np.ones(len(steps), dtype=bool))] + [(f"P{s}", steps == s) for s in (1, 2, 3)]
+        for label, mask in groups:
+            rows.append({
+                "model": f"Confidence {target.upper()}", "split": split, "step": label,
+                "spearman": correlation(score[mask], truth[mask], spearmanr),
+                "pearson": correlation(score[mask], truth[mask], pearsonr),
+                "log_mae": float(np.abs(score[mask] - truth[mask]).mean()),
+            })
+    return rows
+
+
+def remaining_risk(risk, score, ratio):
+    count = min(len(risk), int(round(ratio * len(risk))))
+    if count == 0:
+        return float(risk.mean())
+    selected = np.argpartition(score, len(score) - count)[-count:]
+    keep = np.ones(len(risk), dtype=bool)
+    keep[selected] = False
+    return float(np.where(keep, risk, 0.0).mean())
+
+
+def risk_rows(train, validation, predictions, seed, risk_target):
+    risk = validation[f"true_{risk_target}"].numpy()
+    train_steps = train["step_id"].numpy()
+    train_risk = train[f"true_{risk_target}"].numpy()
+    means = {step: train_risk[train_steps == step].mean() for step in (1, 2, 3)}
+    methods = {
+        "Timestep-only": np.array([means[int(s)] for s in validation["step_id"]]),
+        **{
+            f"Confidence {target.upper()}": score
+            for target, score in predictions.items()
+        },
+        "Oracle": risk,
+    }
+    rows = []
+    rng = np.random.default_rng(seed)
+    for ratio in RATIOS:
+        count = min(len(risk), int(round(ratio * len(risk))))
+        random_risks = []
+        for _ in range(100):
+            chosen = rng.choice(len(risk), count, replace=False) if count else []
+            keep = np.ones(len(risk), dtype=bool)
+            keep[chosen] = False
+            random_risks.append(float(np.where(keep, risk, 0.0).mean()))
+        rows.append({"method": "Random", "fallback_ratio": ratio, "remaining_risk": np.mean(random_risks), "std_if_random": np.std(random_risks)})
+        for method, score in methods.items():
+            rows.append({"method": method, "fallback_ratio": ratio, "remaining_risk": remaining_risk(risk, score, ratio), "std_if_random": ""})
+    return rows
+
+
+def write_csv(path, rows):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(rows[0]))
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def make_plots(validation, risks, predictions, output, risk_target):
+    output.mkdir(parents=True, exist_ok=True)
+    plt.figure(figsize=(7.2, 5.2))
+    confidence_method = f"Confidence {risk_target.upper()}"
+    for method in ("Random", "Timestep-only", confidence_method, "Oracle"):
+        rows = [row for row in risks if row["method"] == method]
+        plt.plot([100 * row["fallback_ratio"] for row in rows], [row["remaining_risk"] for row in rows], marker="o", label=method)
+    plt.xlabel("Fallback ratio (%)")
+    plt.ylabel(f"Remaining {risk_target.upper()} risk")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(output / "risk_coverage.png", dpi=180)
+    plt.close()
+    scores = predictions[risk_target]
+    count = int(round(len(scores) / 3))
+    chosen = np.argpartition(scores, len(scores) - count)[-count:]
+    steps = validation["step_id"].numpy()[chosen]
+    plt.figure(figsize=(5.5, 4.4))
+    plt.bar(("P1", "P2", "P3"), [float((steps == s).mean()) for s in (1, 2, 3)])
+    plt.ylabel("Fraction of selected fallbacks")
+    plt.tight_layout()
+    plt.savefig(output / "fallback_distribution_33pct.png", dpi=180)
+    plt.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--train_features", type=Path, required=True)
+    parser.add_argument("--validation_features", type=Path, required=True)
+    parser.add_argument("--output_dir", type=Path, required=True)
+    parser.add_argument("--epochs", type=int, default=40)
+    parser.add_argument("--batch_size", type=int, default=256)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--targets", nargs="+", choices=TARGETS, default=list(TARGETS))
+    parser.add_argument("--risk_target", choices=TARGETS, default="c1")
+    parser.add_argument("--mlp_dims", nargs="+", type=int, default=[256])
+    args = parser.parse_args()
+    if args.risk_target not in args.targets:
+        parser.error("--risk_target must be included in --targets")
+    if any(dim <= 0 for dim in args.mlp_dims):
+        parser.error("--mlp_dims values must be positive")
+    targets = tuple(dict.fromkeys(args.targets))
+    mlp_dims = tuple(args.mlp_dims)
+    random.seed(args.seed); np.random.seed(args.seed); torch.manual_seed(args.seed)
+    world_size = int(os.environ.get("WORLD_SIZE", 1)); rank = int(os.environ.get("RANK", 0)); local_rank = int(os.environ.get("LOCAL_RANK", 0))
+    if world_size > 1:
+        torch.cuda.set_device(local_rank); dist.init_process_group("nccl")
+    device = torch.device("cuda", local_rank) if torch.cuda.is_available() else torch.device("cpu")
+    train = load_features(args.train_features); validation = load_features(args.validation_features)
+    if rank == 0:
+        for child in ("checkpoints", "plots", "predictions", "tables"):
+            (args.output_dir / child).mkdir(parents=True, exist_ok=True)
+    if world_size > 1: dist.barrier()
+    train_predictions = {}; validation_predictions = {}
+    for target in targets:
+        model = train_head(
+            train, target, device, args.epochs, args.batch_size, args.seed,
+            rank, world_size, mlp_dims,
+        )
+        if rank == 0:
+            torch.save(
+                {
+                    "model": model.state_dict(),
+                    "target": target,
+                    "hidden_dim": train["pooled_hidden"].shape[1],
+                    "timestep_dim": 32,
+                    "mlp_dims": list(mlp_dims),
+                },
+                args.output_dir / "checkpoints" / f"confidence_{target}.pt",
+            )
+            train_predictions[target] = predict(model, train, device)
+            validation_predictions[target] = predict(model, validation, device)
+        if world_size > 1: dist.barrier()
+    if rank != 0:
+        dist.destroy_process_group(); return
+    metrics = metric_rows("train", train_predictions, train) + metric_rows("validation", validation_predictions, validation)
+    risks = risk_rows(
+        train, validation, validation_predictions, args.seed, args.risk_target
+    )
+    write_csv(args.output_dir / "tables" / "confidence_metrics.csv", metrics)
+    write_csv(args.output_dir / "tables" / "risk_coverage.csv", risks)
+    prediction_rows = [{**item, **{f"pred_{target}": float(validation_predictions[target][i]) for target in targets}, **{f"true_{target}": float(validation[f"true_{target}"][i]) for target in targets}} for i, item in enumerate(validation["metadata"])]
+    write_csv(args.output_dir / "predictions" / "validation_predictions.csv", prediction_rows)
+    make_plots(
+        validation, risks, validation_predictions, args.output_dir / "plots",
+        args.risk_target,
+    )
+    at_33 = {row["method"]: float(row["remaining_risk"]) for row in risks if math.isclose(row["fallback_ratio"], 1 / 3)}
+    confidence_method = f"Confidence {args.risk_target.upper()}"
+    target_metrics = {row["step"]: row for row in metrics if row["split"] == "validation" and row["model"] == confidence_method}
+    scores = validation_predictions[args.risk_target]; count = int(round(len(scores) / 3)); chosen = np.argpartition(scores, len(scores) - count)[-count:]
+    chosen_mask = np.zeros(len(scores), dtype=bool); chosen_mask[chosen] = True; steps = validation["step_id"].numpy()
+    summary = {
+        "protocol": "WorldPlay fulltrain100 (8400 transitions); independent validation25 (2100 transitions); no validation tuning",
+        "targets": list(targets), "risk_target": args.risk_target,
+        "mlp_dims": list(mlp_dims),
+        "train_samples": len(train["step_id"]), "validation_samples": len(validation["step_id"]),
+        "risk_target_validation_metrics": target_metrics,
+        "remaining_risk_at_33pct": at_33,
+        "gain_vs_random": (at_33["Random"] - at_33[confidence_method]) / at_33["Random"],
+        "oracle_gap": (at_33[confidence_method] - at_33["Oracle"]) / max(at_33["Oracle"], 1e-12),
+        "routing_at_33pct": {f"P{s}": {"selection_fraction": float((steps[chosen_mask] == s).mean()), "within_step_fallback_rate": float(chosen_mask[steps == s].mean())} for s in (1, 2, 3)},
+    }
+    if args.risk_target == "c1":
+        summary["c1_validation_metrics"] = target_metrics
+    (args.output_dir / "summary.json").write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n")
+    (args.output_dir / "summary.md").write_text(
+        "# HY-WorldPlay offline confidence validation\n\n" + summary["protocol"] + "\n\n" +
+        f"## {args.risk_target.upper()} validation Spearman\n\n" + "\n".join(f"- {key}: {value['spearman']:.4f}" for key, value in target_metrics.items()) +
+        f"\n\n## 33.3% fallback remaining {args.risk_target.upper()} risk\n\n" + "\n".join(f"- {key}: {value:.8g}" for key, value in at_33.items()) + "\n"
+    )
+    print(json.dumps(summary, indent=2), flush=True)
+    if world_size > 1: dist.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()

tools/validate_predictor_dataset.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Validate Predictor safetensors files without loading the Teacher."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from safetensors.torch import load_file
+
+from predictor_data.schema import SCHEMA_VERSION, validate_case_tensors, validate_chunk_tensors
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", default="datasets/predictor_v1")
+    parser.add_argument("--expected_cases", type=int, default=None)
+    parser.add_argument("--expected_chunks_per_case", type=int, default=None)
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    manifest = root / "manifest.jsonl"
+    if not manifest.is_file():
+        raise FileNotFoundError(manifest)
+    records = [json.loads(line) for line in manifest.read_text(encoding="utf-8").splitlines() if line]
+    if len({(r["case_id"], r["seed"], r["chunk_id"]) for r in records}) != len(records):
+        raise ValueError("Duplicate manifest keys")
+
+    seen_cases = set()
+    per_case: dict[int, int] = {}
+    for record in records:
+        if record["schema_version"] != SCHEMA_VERSION:
+            raise ValueError(f"Unexpected schema: {record['schema_version']}")
+        case_id = int(record["case_id"])
+        if case_id not in seen_cases:
+            validate_case_tensors(load_file(str(root / record["case_tensor_file"]), device="cpu"))
+            seen_cases.add(case_id)
+        validate_chunk_tensors(load_file(str(root / record["tensor_file"]), device="cpu"))
+        per_case[case_id] = per_case.get(case_id, 0) + 1
+
+    if args.expected_cases is not None and len(seen_cases) != args.expected_cases:
+        raise ValueError(f"Expected {args.expected_cases} cases, found {len(seen_cases)}")
+    if args.expected_chunks_per_case is not None:
+        bad = {case: count for case, count in per_case.items() if count != args.expected_chunks_per_case}
+        if bad:
+            raise ValueError(f"Unexpected chunks per case: {bad}")
+    print(json.dumps({"records": len(records), "cases": len(seen_cases), "chunks_per_case": per_case}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

tools/validate_predictor_prefeature_dataset.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Validate BF16 prefeature files, targets, task cardinality, and videos."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter
+from pathlib import Path
+
+from safetensors.torch import load_file
+
+from predictor_data.prefeature_schema import (
+    CONTEXT_BLOCK_IDS,
+    SCHEMA_VERSION_PREFEATURE,
+    validate_case_tensors,
+    validate_context_prefeature,
+    validate_step_tensors,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--manifest",
+        type=Path,
+        default=Path("/mnt/local_nvme/zoubin/cz/hyworldplay_predictor_prefeature_v4/manifest.jsonl"),
+    )
+    parser.add_argument("--expected_records", type=int, default=3200)
+    parser.add_argument("--check_videos", action=argparse.BooleanOptionalAction, default=True)
+    args = parser.parse_args()
+    manifest = args.manifest.resolve()
+    root = manifest.parent
+    with manifest.open("r", encoding="utf-8") as handle:
+        records = [json.loads(line) for line in handle if line.strip()]
+    if len(records) != args.expected_records:
+        raise ValueError(f"Found {len(records)} records, expected {args.expected_records}")
+    keys = Counter()
+    cases_checked = set()
+    frame_histogram = Counter()
+    for record in records:
+        if record["schema_version"] != SCHEMA_VERSION_PREFEATURE:
+            raise ValueError("Schema mismatch")
+        key = (int(record["case_id"]), int(record["action_id"]), int(record["chunk_id"]))
+        keys[key] += 1
+        if key[0] not in cases_checked:
+            validate_case_tensors(load_file(str(root / record["case_tensor_file"]), device="cpu"))
+            cases_checked.add(key[0])
+        validate_step_tensors(load_file(str(root / record["step_tensor_file"]), device="cpu"))
+        block_frames = []
+        selected = None
+        for block_id in CONTEXT_BLOCK_IDS:
+            value = load_file(str(root / record["context_tensor_files"][str(block_id)]), device="cpu")
+            block_frames.append(validate_context_prefeature(block_id, value))
+            current = value["selected_frame_indices"]
+            if selected is not None and not current.equal(selected):
+                raise ValueError(f"Selected frame mismatch across blocks for {key}")
+            selected = current
+        if len(set(block_frames)) != 1 or block_frames[0] != int(record["context_frames"]):
+            raise ValueError(f"Context frame mismatch for {key}")
+        frame_histogram[block_frames[0]] += 1
+    duplicates = [key for key, count in keys.items() if count != 1]
+    if duplicates:
+        raise ValueError(f"Duplicate keys: {duplicates[:10]}")
+    if args.check_videos:
+        missing_videos = [
+            (case_id, action_id)
+            for case_id in range(100) for action_id in range(4)
+            if not (root / "videos" / f"case_{case_id:04d}_action_{action_id:02d}.mp4").is_file()
+        ]
+        if missing_videos:
+            raise ValueError(f"Missing videos: {missing_videos[:10]}")
+    print(json.dumps({
+        "status": "ok", "records": len(records), "cases": len(cases_checked),
+        "frame_histogram": dict(sorted(frame_histogram.items())),
+    }, indent=2))
+
+
+if __name__ == "__main__":
+    main()

tools/validate_predictor_text_kv_all54.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Validate cardinality, schema, shape, dtype, and provenance of Text K/V cache files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from safetensors import safe_open
+from safetensors.torch import load_file
+
+from predictor_data.text_kv_schema import (
+    SCHEMA_VERSION_TEXT_KV_ALL54,
+    validate_text_kv_all54,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--expected_cases", type=int, default=100)
+    args = parser.parse_args()
+    root = args.root.resolve()
+    files = sorted(root.glob("case_*_text_kv_exact_all54_bf16.safetensors"))
+    if len(files) != args.expected_cases:
+        raise ValueError(f"Expected {args.expected_cases} files, found {len(files)}")
+    total_bytes = 0
+    for case_id, path in enumerate(files):
+        expected_name = f"case_{case_id:04d}_text_kv_exact_all54_bf16.safetensors"
+        if path.name != expected_name:
+            raise ValueError(f"Expected {expected_name}, found {path.name}")
+        with safe_open(str(path), framework="pt", device="cpu") as handle:
+            metadata = handle.metadata() or {}
+        if metadata.get("schema_version") != SCHEMA_VERSION_TEXT_KV_ALL54:
+            raise ValueError(f"Schema mismatch: {path}")
+        if metadata.get("case_id") != str(case_id):
+            raise ValueError(f"Case metadata mismatch: {path}")
+        validate_text_kv_all54(load_file(str(path), device="cpu"))
+        total_bytes += path.stat().st_size
+        print(f"[ok] {case_id + 1}/{len(files)} {path.name}", flush=True)
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "schema_version": SCHEMA_VERSION_TEXT_KV_ALL54,
+                "cases": len(files),
+                "total_bytes": total_bytes,
+                "total_gib": total_bytes / 2**30,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

tools/validate_predictor_v2_dataset.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Validate Predictor-v2 manifests, BF16 targets, and four-layer context KV."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+
+from safetensors.torch import load_file
+
+from predictor_data.v2_schema import (
+    CONTEXT_BLOCK_IDS,
+    SCHEMA_VERSION_V2,
+    validate_case_tensors_v2,
+    validate_step_tensors_v2,
+    validate_vision_context_v2,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", default="datasets/predictor_v2/manifest.jsonl")
+    parser.add_argument("--expected_cases", type=int, default=10)
+    parser.add_argument("--expected_chunks_per_case", type=int, default=16)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    manifest = Path(args.manifest).resolve()
+    root = manifest.parent
+    with manifest.open("r", encoding="utf-8") as handle:
+        records = [json.loads(line) for line in handle if line.strip()]
+    if len(records) != args.expected_cases * args.expected_chunks_per_case:
+        raise ValueError(f"Unexpected record count: {len(records)}")
+
+    counts = Counter()
+    seen_cases = set()
+    frame_histogram: dict[int, Counter] = defaultdict(Counter)
+    text_padded_tokens = set()
+    text_valid_tokens: dict[int, int] = {}
+    context_padded_tokens = set()
+    for record in records:
+        if record["schema_version"] != SCHEMA_VERSION_V2:
+            raise ValueError(f"Unexpected schema: {record['schema_version']}")
+        key = (int(record["case_id"]), int(record["seed"]), int(record["chunk_id"]))
+        counts[key] += 1
+        case_id = key[0]
+        if case_id not in seen_cases:
+            case = load_file(str(root / record["case_tensor_file"]), device="cpu")
+            text_valid_tokens[case_id] = validate_case_tensors_v2(case)
+            text_padded_tokens.add(int(case["text_valid_mask"].shape[1]))
+            seen_cases.add(case_id)
+        steps = load_file(str(root / record["step_tensor_file"]), device="cpu")
+        validate_step_tensors_v2(steps)
+        frame_counts = []
+        for block_id in CONTEXT_BLOCK_IDS:
+            context = load_file(
+                str(root / record["context_tensor_files"][str(block_id)]),
+                device="cpu",
+            )
+            frames = validate_vision_context_v2(block_id, context)
+            context_padded_tokens.add(int(context["context_valid_mask"].shape[1]))
+            frame_counts.append(frames)
+            frame_histogram[block_id][frames] += 1
+        if len(set(frame_counts)) != 1 or frame_counts[0] != int(record["context_frames"]):
+            raise ValueError(f"Context frame mismatch for {key}: {frame_counts}")
+    duplicates = [key for key, count in counts.items() if count != 1]
+    if duplicates:
+        raise ValueError(f"Duplicate manifest keys: {duplicates[:5]}")
+    if len(text_padded_tokens) != 1:
+        raise ValueError(f"Text KV is not uniformly padded: {sorted(text_padded_tokens)}")
+    if len(context_padded_tokens) != 1:
+        raise ValueError(
+            f"Context Vision KV is not uniformly padded: {sorted(context_padded_tokens)}"
+        )
+    payload = {
+        "root": str(root),
+        "records": len(records),
+        "cases": len(seen_cases),
+        "context_blocks": list(CONTEXT_BLOCK_IDS),
+        "text_padded_tokens": next(iter(text_padded_tokens)),
+        "text_valid_tokens": dict(sorted(text_valid_tokens.items())),
+        "context_padded_tokens": next(iter(context_padded_tokens)),
+        "context_frame_histogram": {
+            str(block_id): dict(sorted(counter.items()))
+            for block_id, counter in frame_histogram.items()
+        },
+        "status": "ok",
+    }
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

tools/video_review_server.py

@@ -0,0 +1,1031 @@
+#!/usr/bin/env python3
+"""A zero-dependency video review and download server."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import mimetypes
+import os
+import re
+import secrets
+import threading
+import time
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path, PurePosixPath
+from urllib.parse import parse_qs, quote, urlparse
+
+
+VIDEO_EXTENSIONS = {".mp4", ".webm", ".mov", ".mkv", ".avi", ".m4v"}
+CHUNK_SIZE = 256 * 1024
+DEFAULT_REFRESH_INTERVAL = 30.0
+DEFAULT_SETTLE_SECONDS = 3.0
+
+INDEX_HTML = r"""<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Projects 视频审阅</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #0b0d12; --panel: #121620; --line: #262c3a;
+      --text: #e8ecf5; --muted: #8d96a8; --accent: #7c9cff;
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: var(--bg); color: var(--text);
+      font: 14px/1.45 ui-sans-serif, system-ui, -apple-system, sans-serif; }
+    .app { height: 100vh; display: grid;
+      grid-template-columns: var(--sidebar-width, 360px) 6px minmax(0, 1fr); }
+    aside { min-height: 0; display: flex; flex-direction: column; border-right: 1px solid var(--line);
+      background: var(--panel); }
+    .resize-handle { position: relative; z-index: 10; background: var(--line); cursor: col-resize;
+      touch-action: none; transition: background .15s; }
+    .resize-handle::after { content: ""; position: absolute; inset: 0 -4px; }
+    .resize-handle:hover, .resize-handle:focus, .resize-handle.dragging {
+      background: var(--accent); outline: none; }
+    header { padding: 18px; border-bottom: 1px solid var(--line); }
+    h1 { margin: 0 0 5px; font-size: 16px; }
+    .summary, .hint, .meta { color: var(--muted); font-size: 12px; }
+    .catalog-line { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+    .catalog-refresh { flex: none; padding: 3px 7px; border: 1px solid var(--line);
+      border-radius: 5px; background: #171c28; color: #cbd2e2; cursor: pointer; font-size: 11px; }
+    .catalog-refresh:hover { border-color: var(--accent); color: white; }
+    .catalog-refresh:disabled { cursor: wait; opacity: .65; }
+    input { width: 100%; margin-top: 14px; padding: 10px 12px; color: var(--text);
+      background: #0c1018; border: 1px solid var(--line); border-radius: 8px; outline: none; }
+    input:focus { border-color: var(--accent); }
+    #tree { overflow: auto; padding: 10px 8px 24px; }
+    details details { margin-left: 14px; }
+    summary { cursor: pointer; padding: 5px 7px; color: #b8c0d1; white-space: nowrap; }
+    .file { width: 100%; border: 0; border-radius: 6px; background: transparent; color: #b7becc;
+      padding: 6px 8px 6px 25px; text-align: left; cursor: grab; white-space: nowrap;
+      overflow: hidden; text-overflow: ellipsis; }
+    .file:active { cursor: grabbing; }
+    .file:hover { background: #1b2130; color: white; }
+    .file.active { background: #253052; color: white; }
+    .search-result { display: block; }
+    main { min-width: 0; min-height: 0; display: flex; flex-direction: column; }
+    .topbar { min-height: 66px; display: flex; justify-content: space-between; gap: 16px;
+      align-items: center; padding: 12px 20px; border-bottom: 1px solid var(--line); }
+    .path { min-width: 0; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .counter { flex: none; color: var(--muted); }
+    .workspace-actions { flex: none; display: flex; align-items: center; gap: 7px; }
+    .toolbar-button, .pane-download, .pane-close { border: 1px solid var(--line); border-radius: 6px;
+      background: #171c28; color: #cbd2e2; cursor: pointer; }
+    .toolbar-button { padding: 6px 10px; }
+    .toolbar-button:hover, .pane-download:hover, .pane-close:hover {
+      border-color: var(--accent); color: white; }
+    .toolbar-button.active { border-color: var(--accent); background: #253052; color: white; }
+    .stage { min-height: 0; flex: 1; display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(min(100%, 420px), 1fr));
+      grid-auto-rows: minmax(280px, 1fr); align-content: stretch; gap: 8px; padding: 8px;
+      overflow: auto;
+      background: radial-gradient(circle at 50% 40%, #171c28, #090b0f 65%); }
+    .stage.layout-horizontal { grid-template-columns:
+      repeat(var(--pane-count, 1), minmax(360px, 1fr)); grid-template-rows: 1fr;
+      grid-auto-rows: 1fr; }
+    .stage.layout-vertical { grid-template-columns: 1fr; grid-template-rows:
+      repeat(var(--pane-count, 1), minmax(280px, 1fr)); grid-auto-rows: minmax(280px, 1fr); }
+    .stage.drop-target { box-shadow: inset 0 0 0 2px var(--accent);
+      background: #11182a; }
+    .pane { min-width: 0; min-height: 280px; display: flex; flex-direction: column;
+      border: 1px solid var(--line); background: #090b10; overflow: hidden; }
+    .pane.active { border-color: var(--accent); box-shadow: 0 0 0 1px #7c9cff55; }
+    .pane-header { min-height: 38px; display: flex; align-items: center; gap: 9px;
+      padding: 6px 7px 6px 11px; border-bottom: 1px solid var(--line); background: #151a25; }
+    .pane-heading { min-width: 0; flex: 1; }
+    .pane-title, .pane-path { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .pane-title { font-size: 12px; font-weight: 650; }
+    .pane-path { color: var(--muted); font-size: 10px; }
+    .pane-download { padding: 4px 9px; text-decoration: none; font-size: 12px; white-space: nowrap; }
+    .pane-close { width: 26px; height: 26px; padding: 0; font-size: 17px; }
+    .pane video { display: block; width: 100%; min-height: 0; flex: 1; object-fit: contain;
+      background: #000; }
+    .empty { grid-column: 1 / -1; align-self: center; justify-self: center;
+      text-align: center; color: var(--muted); pointer-events: none; }
+    .empty strong { display: block; color: var(--text); font-size: 18px; margin-bottom: 8px; }
+    .status { min-height: 38px; padding: 10px 20px; border-top: 1px solid var(--line);
+      display: flex; justify-content: space-between; color: var(--muted); font-size: 12px; }
+    @media (max-width: 760px) {
+      .app { grid-template-columns: 1fr; grid-template-rows: 44vh 56vh; }
+      .resize-handle { display: none; }
+      aside { border-right: 0; border-bottom: 1px solid var(--line); }
+      .toolbar-button { padding: 5px 7px; font-size: 11px; }
+      .stage { grid-template-columns: 1fr; grid-auto-rows: minmax(240px, 1fr); }
+    }
+  </style>
+</head>
+<body>
+<div class="app">
+  <aside>
+    <header>
+      <h1>Projects 视频审阅</h1>
+      <div class="catalog-line">
+        <div class="summary" id="summary">正在读取目录…</div>
+        <button class="catalog-refresh" id="refreshCatalog" type="button">立即刷新</button>
+      </div>
+      <input id="search" type="search" placeholder="按路径或文件名筛选…" autocomplete="off">
+    </header>
+    <div id="tree"></div>
+  </aside>
+  <div class="resize-handle" id="resizeHandle" role="separator" aria-label="调整文件栏宽度"
+    aria-orientation="vertical" tabindex="0" title="拖动调整宽度，双击恢复默认"></div>
+  <main>
+    <div class="topbar">
+      <div>
+        <div class="path" id="currentPath">尚未选择视频</div>
+        <div class="meta" id="currentMeta">点击文件在当前窗口打开，或拖入工作区新增窗口</div>
+      </div>
+      <div class="workspace-actions">
+        <button class="toolbar-button layout-button active" data-layout="grid" type="button"
+          title="根据空间自动排列">网格</button>
+        <button class="toolbar-button layout-button" data-layout="horizontal" type="button"
+          title="视频左右排列">左右</button>
+        <button class="toolbar-button layout-button" data-layout="vertical" type="button"
+          title="视频上下排列">上下</button>
+        <button class="toolbar-button" id="playAll" type="button">全部播放</button>
+        <button class="toolbar-button" id="pauseAll" type="button">全部暂停</button>
+        <button class="toolbar-button" id="resetAll" type="button">全部回零</button>
+        <div class="counter" id="counter">0 个窗口</div>
+      </div>
+    </div>
+    <div class="stage" id="workspace">
+      <div class="empty" id="empty">
+        <strong>拖入视频开始多窗口比较</strong>
+        点击文件使用单窗口；拖动多个文件到这里可并排查看。
+      </div>
+    </div>
+    <div class="status">
+      <span id="status">就绪</span>
+      <span>拖入新增窗口 · 点击替换活动窗口 · J/K/L 控制活动窗口</span>
+    </div>
+  </main>
+</div>
+<script>
+  const treeEl = document.querySelector('#tree');
+  const workspace = document.querySelector('#workspace');
+  const empty = document.querySelector('#empty');
+  const statusEl = document.querySelector('#status');
+  const searchEl = document.querySelector('#search');
+  const appEl = document.querySelector('.app');
+  const resizeHandle = document.querySelector('#resizeHandle');
+  const summaryEl = document.querySelector('#summary');
+  const refreshCatalogButton = document.querySelector('#refreshCatalog');
+  let videos = [];
+  let catalogRevision = 0;
+  let catalogPolling = false;
+  const panes = new Map();
+  let activePaneId = null;
+
+  function setSidebarWidth(value) {
+    const maxWidth = Math.min(1000, window.innerWidth * 0.72);
+    const width = Math.max(260, Math.min(maxWidth, value));
+    appEl.style.setProperty('--sidebar-width', `${width}px`);
+    localStorage.setItem('hy-video-review-sidebar-width', String(width));
+  }
+
+  const savedSidebarWidth = Number(localStorage.getItem('hy-video-review-sidebar-width'));
+  if (savedSidebarWidth) setSidebarWidth(savedSidebarWidth);
+
+  let resizing = false;
+  resizeHandle.addEventListener('pointerdown', event => {
+    resizing = true;
+    resizeHandle.classList.add('dragging');
+    resizeHandle.setPointerCapture(event.pointerId);
+    document.body.style.userSelect = 'none';
+  });
+  resizeHandle.addEventListener('pointermove', event => {
+    if (resizing) setSidebarWidth(event.clientX);
+  });
+  resizeHandle.addEventListener('pointerup', event => {
+    resizing = false;
+    resizeHandle.classList.remove('dragging');
+    resizeHandle.releasePointerCapture(event.pointerId);
+    document.body.style.userSelect = '';
+  });
+  resizeHandle.addEventListener('dblclick', () => setSidebarWidth(360));
+  resizeHandle.addEventListener('keydown', event => {
+    if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
+    event.preventDefault();
+    const current = document.querySelector('aside').getBoundingClientRect().width;
+    setSidebarWidth(current + (event.key === 'ArrowRight' ? 24 : -24));
+  });
+
+  function setWorkspaceLayout(layout) {
+    if (!['grid', 'horizontal', 'vertical'].includes(layout)) layout = 'grid';
+    workspace.classList.remove('layout-horizontal', 'layout-vertical');
+    if (layout !== 'grid') workspace.classList.add(`layout-${layout}`);
+    document.querySelectorAll('.layout-button').forEach(button => {
+      button.classList.toggle('active', button.dataset.layout === layout);
+    });
+    localStorage.setItem('hy-video-review-layout', layout);
+  }
+
+  document.querySelectorAll('.layout-button').forEach(button => {
+    button.addEventListener('click', () => setWorkspaceLayout(button.dataset.layout));
+  });
+  setWorkspaceLayout(localStorage.getItem('hy-video-review-layout') || 'grid');
+
+  const formatBytes = n => {
+    const units = ['B', 'KiB', 'MiB', 'GiB'];
+    let i = 0, value = n;
+    while (value >= 1024 && i < units.length - 1) { value /= 1024; i++; }
+    return `${value.toFixed(i ? 1 : 0)} ${units[i]}`;
+  };
+
+  function makeTree(items) {
+    const root = {dirs: new Map(), files: []};
+    for (const item of items) {
+      const parts = item.path.split('/');
+      const file = parts.pop();
+      let node = root;
+      for (const part of parts) {
+        if (!node.dirs.has(part)) node.dirs.set(part, {dirs: new Map(), files: []});
+        node = node.dirs.get(part);
+      }
+      node.files.push({...item, name: file});
+    }
+    return root;
+  }
+
+  function fileButton(item, extraClass = '') {
+    const button = document.createElement('button');
+    button.className = `file ${extraClass}`;
+    button.dataset.path = item.path;
+    button.title = `${item.path}\n${formatBytes(item.size)}`;
+    button.textContent = item.name || item.path;
+    button.draggable = true;
+    button.addEventListener('click', () => selectVideo(item.path));
+    button.addEventListener('dragstart', event => {
+      event.dataTransfer.effectAllowed = 'copy';
+      event.dataTransfer.setData('application/x-hy-video-path', item.path);
+      event.dataTransfer.setData('text/plain', item.path);
+    });
+    return button;
+  }
+
+  function renderNode(node, container) {
+    const dirs = [...node.dirs].sort((a, b) => a[0].localeCompare(b[0], undefined, {numeric:true}));
+    for (const [name, child] of dirs) {
+      const details = document.createElement('details');
+      const summary = document.createElement('summary');
+      summary.textContent = `📁 ${name}`;
+      details.append(summary);
+      renderNode(child, details);
+      container.append(details);
+    }
+    node.files.sort((a, b) => a.name.localeCompare(b.name, undefined, {numeric:true}));
+    for (const item of node.files) container.append(fileButton(item));
+  }
+
+  function render(filter = '') {
+    treeEl.replaceChildren();
+    const query = filter.trim().toLowerCase();
+    if (query) {
+      const matches = videos.filter(v => v.path.toLowerCase().includes(query)).slice(0, 500);
+      for (const item of matches) {
+        const button = fileButton(item, 'search-result');
+        button.textContent = item.path;
+        treeEl.append(button);
+      }
+      if (!matches.length) treeEl.textContent = '没有匹配的视频';
+    } else {
+      renderNode(makeTree(videos), treeEl);
+    }
+    markActive();
+  }
+
+  function markActive() {
+    document.querySelectorAll('.file.active').forEach(el => el.classList.remove('active'));
+    const pane = panes.get(activePaneId);
+    if (pane?.path) {
+      document.querySelectorAll('.file').forEach(el => {
+        if (el.dataset.path === pane.path) el.classList.add('active');
+      });
+    }
+  }
+
+  function paneId() {
+    return `pane-${globalThis.crypto?.randomUUID?.() ||
+      `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
+  }
+
+  function createPane() {
+    const id = paneId();
+    const element = document.createElement('article');
+    element.className = 'pane';
+    element.dataset.slot = id;
+
+    const header = document.createElement('div');
+    header.className = 'pane-header';
+    const heading = document.createElement('div');
+    heading.className = 'pane-heading';
+    const title = document.createElement('div');
+    title.className = 'pane-title';
+    title.textContent = '正在准���…';
+    const pathLabel = document.createElement('div');
+    pathLabel.className = 'pane-path';
+    const download = document.createElement('a');
+    download.className = 'pane-download';
+    download.textContent = '下载';
+    download.title = '从公网下载这个视频';
+    download.hidden = true;
+    const close = document.createElement('button');
+    close.className = 'pane-close';
+    close.type = 'button';
+    close.title = '关闭窗口并释放带宽';
+    close.setAttribute('aria-label', '关闭视频窗口');
+    close.textContent = '×';
+    const video = document.createElement('video');
+    video.controls = true;
+    video.playsInline = true;
+    video.preload = 'metadata';
+
+    heading.append(title, pathLabel);
+    header.append(heading, download, close);
+    element.append(header, video);
+    workspace.append(element);
+
+    const pane = {id, element, title, pathLabel, download, video, token: '', path: '', serial: 0};
+    panes.set(id, pane);
+    element.addEventListener('pointerdown', () => setActivePane(id));
+    close.addEventListener('click', event => {
+      event.stopPropagation();
+      closePane(id);
+    });
+    video.addEventListener('error', () => {
+      if (video.error) statusEl.textContent =
+        `${title.textContent} 无法播放（错误 ${video.error.code}）`;
+    });
+    video.addEventListener('playing', () => {
+      statusEl.textContent = `${panes.size} 个窗口 · 正在播放`;
+    });
+    setActivePane(id);
+    updateWorkspaceUI();
+    return pane;
+  }
+
+  function setActivePane(id) {
+    if (!panes.has(id)) return;
+    activePaneId = id;
+    panes.forEach(pane => pane.element.classList.toggle('active', pane.id === id));
+    updateWorkspaceUI();
+  }
+
+  function releaseToken(slot, token) {
+    if (!token) return;
+    fetch('/api/release', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({slot, token}),
+      keepalive: true
+    }).catch(() => {});
+  }
+
+  function detachMedia(pane) {
+    pane.video.pause();
+    pane.video.removeAttribute('src');
+    pane.video.load();
+    if (pane.token) releaseToken(pane.id, pane.token);
+    pane.token = '';
+  }
+
+  function closePane(id) {
+    const pane = panes.get(id);
+    if (!pane) return;
+    pane.serial++;
+    detachMedia(pane);
+    pane.element.remove();
+    panes.delete(id);
+    if (activePaneId === id) activePaneId = panes.keys().next().value || null;
+    if (activePaneId) panes.get(activePaneId).element.classList.add('active');
+    updateWorkspaceUI();
+    statusEl.textContent = panes.size ? `剩余 ${panes.size} 个窗口` : '所有视频带宽已释放';
+  }
+
+  function updateWorkspaceUI() {
+    empty.style.display = panes.size ? 'none' : '';
+    workspace.style.setProperty('--pane-count', String(Math.max(1, panes.size)));
+    document.querySelector('#counter').textContent = `${panes.size} 个窗口`;
+    const pane = panes.get(activePaneId);
+    document.querySelector('#currentPath').textContent = pane?.path || '尚未选择视频';
+    document.querySelector('#currentMeta').textContent = pane?.path
+      ? `${formatBytes(videos.find(item => item.path === pane.path)?.size || 0)} · 活动窗口`
+      : '点击文件在当前窗口打开，或拖入工作区新增窗口';
+    markActive();
+  }
+
+  async function loadIntoPane(pane, path) {
+    const index = videos.findIndex(v => v.path === path);
+    if (index < 0) return;
+    const serial = ++pane.serial;
+    const item = videos[index];
+
+    detachMedia(pane);
+    pane.path = path;
+    pane.title.textContent = path.split('/').pop();
+    pane.pathLabel.textContent = path;
+    pane.pathLabel.title = path;
+    pane.download.href = `/download?path=${encodeURIComponent(path)}`;
+    pane.download.setAttribute('download', path.split('/').pop());
+    pane.download.hidden = false;
+    setActivePane(pane.id);
+    statusEl.textContent = '正在申请窗口带宽…';
+
+    try {
+      const response = await fetch('/api/select', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({path, slot: pane.id})
+      });
+      if (!response.ok) throw new Error(await response.text());
+      const {token} = await response.json();
+      if (!panes.has(pane.id) || serial !== pane.serial) {
+        releaseToken(pane.id, token);
+        return;
+      }
+
+      pane.token = token;
+      pane.video.src = `/media?path=${encodeURIComponent(path)}&slot=${encodeURIComponent(pane.id)}` +
+        `&token=${encodeURIComponent(token)}`;
+      pane.video.load();
+      pane.video.play().catch(() => {});
+      statusEl.textContent = `${panes.size} 个窗口占用视频带宽`;
+      updateWorkspaceUI();
+    } catch (error) {
+      if (serial !== pane.serial) return;
+      statusEl.textContent = `加载失败：${error.message}`;
+    }
+  }
+
+  function selectVideo(path) {
+    const pane = panes.get(activePaneId) || createPane();
+    loadIntoPane(pane, path);
+  }
+
+  function addVideoPane(path) {
+    loadIntoPane(createPane(), path);
+  }
+
+  workspace.addEventListener('dragover', event => {
+    event.preventDefault();
+    event.dataTransfer.dropEffect = 'copy';
+    workspace.classList.add('drop-target');
+  });
+  workspace.addEventListener('dragleave', event => {
+    if (!workspace.contains(event.relatedTarget)) workspace.classList.remove('drop-target');
+  });
+  workspace.addEventListener('drop', event => {
+    event.preventDefault();
+    workspace.classList.remove('drop-target');
+    const path = event.dataTransfer.getData('application/x-hy-video-path') ||
+      event.dataTransfer.getData('text/plain');
+    if (videos.some(item => item.path === path)) addVideoPane(path);
+  });
+
+  document.querySelector('#playAll').addEventListener('click', () => {
+    panes.forEach(pane => pane.video.play().catch(() => {}));
+  });
+  document.querySelector('#pauseAll').addEventListener('click', () => {
+    panes.forEach(pane => pane.video.pause());
+    statusEl.textContent = `已暂停 ${panes.size} 个窗口`;
+  });
+  document.querySelector('#resetAll').addEventListener('click', () => {
+    panes.forEach(pane => { pane.video.currentTime = 0; });
+    statusEl.textContent = `已将 ${panes.size} 个窗口回零`;
+  });
+
+  searchEl.addEventListener('input', () => render(searchEl.value));
+  document.addEventListener('keydown', event => {
+    if (event.target === searchEl) return;
+    const pane = panes.get(activePaneId);
+    if (!pane) return;
+    const index = videos.findIndex(item => item.path === pane.path);
+    if (event.key.toLowerCase() === 'j' && index > 0) selectVideo(videos[index - 1].path);
+    if (event.key.toLowerCase() === 'l' && index + 1 < videos.length) selectVideo(videos[index + 1].path);
+    if (event.key.toLowerCase() === 'k') {
+      event.preventDefault();
+      if (pane.video.src) pane.video.paused ? pane.video.play() : pane.video.pause();
+    }
+  });
+  window.addEventListener('beforeunload', () => {
+    panes.forEach(pane => {
+      if (!pane.token) return;
+      navigator.sendBeacon('/api/release', new Blob(
+        [JSON.stringify({slot: pane.id, token: pane.token})],
+        {type: 'application/json'}
+      ));
+    });
+  });
+
+  function updateCatalogSummary(data) {
+    const count = data.video_count ?? videos.length;
+    const suffix = data.refreshing ? ' · 正在扫描新视频…' : ' · 自动更新';
+    summaryEl.textContent =
+      `${count.toLocaleString()} 个视频 · ${formatBytes(data.total_size || 0)}${suffix}`;
+    refreshCatalogButton.disabled = Boolean(data.refreshing);
+    refreshCatalogButton.textContent = data.refreshing ? '扫描中…' : '立即刷新';
+  }
+
+  function applyCatalog(data, announce = false) {
+    const previousCount = videos.length;
+    videos = data.videos;
+    catalogRevision = data.revision;
+    updateCatalogSummary(data);
+    render(searchEl.value);
+    updateWorkspaceUI();
+    if (announce && videos.length !== previousCount) {
+      const difference = videos.length - previousCount;
+      statusEl.textContent = difference > 0
+        ? `目录已自动更新：新增 ${difference} 个视频`
+        : `目录已自动更新：减少 ${Math.abs(difference)} 个视频`;
+    }
+  }
+
+  async function fetchCatalog(announce = false) {
+    const response = await fetch('/api/videos', {cache: 'no-store'});
+    if (!response.ok) throw new Error(await response.text());
+    applyCatalog(await response.json(), announce);
+  }
+
+  async function pollCatalogStatus() {
+    if (catalogPolling) return;
+    catalogPolling = true;
+    try {
+      const response = await fetch('/api/status', {cache: 'no-store'});
+      if (!response.ok) throw new Error(await response.text());
+      const data = await response.json();
+      updateCatalogSummary(data);
+      if (data.revision !== catalogRevision) await fetchCatalog(true);
+    } catch (error) {
+      summaryEl.textContent = `自动更新检查失败：${error.message}`;
+    } finally {
+      catalogPolling = false;
+    }
+  }
+
+  refreshCatalogButton.addEventListener('click', async () => {
+    refreshCatalogButton.disabled = true;
+    refreshCatalogButton.textContent = '扫描中…';
+    statusEl.textContent = '正在后台扫描新视频，已打开的窗口不会中断';
+    try {
+      const response = await fetch('/api/refresh', {method: 'POST'});
+      if (!response.ok) throw new Error(await response.text());
+      updateCatalogSummary(await response.json());
+    } catch (error) {
+      statusEl.textContent = `刷新失败：${error.message}`;
+      refreshCatalogButton.disabled = false;
+      refreshCatalogButton.textContent = '立即刷新';
+    }
+  });
+
+  fetchCatalog().catch(error => {
+    summaryEl.textContent = `目录读取失败：${error.message}`;
+  });
+  setInterval(pollCatalogStatus, 5000);
+</script>
+</body>
+</html>
+"""
+
+
+class ReviewState:
+    def __init__(
+        self,
+        root: Path,
+        refresh_interval: float = DEFAULT_REFRESH_INTERVAL,
+        settle_seconds: float = DEFAULT_SETTLE_SECONDS,
+    ):
+        self.root = root.resolve()
+        self.refresh_interval = max(0.0, refresh_interval)
+        self.settle_seconds = max(0.0, settle_seconds)
+        self.lease_lock = threading.Lock()
+        self.catalog_lock = threading.Lock()
+        self.refresh_guard = threading.Lock()
+        self.leases: dict[str, tuple[str, str]] = {}
+        self.refreshing = False
+        self.last_scan_started = time.time()
+        initial = self._scan_raw()
+        self.videos = [self._public_item(item) for item in initial]
+        self.paths = {str(item["path"]) for item in self.videos}
+        self.signatures = {
+            str(item["path"]): (int(item["size"]), int(item["mtime_ns"]))
+            for item in initial
+        }
+        self.total_size = sum(int(item["size"]) for item in self.videos)
+        self.revision = 1
+        self.last_scan_finished = time.time()
+        if self.refresh_interval > 0:
+            threading.Thread(
+                target=self._auto_refresh_loop,
+                name="video-catalog-auto-refresh",
+                daemon=True,
+            ).start()
+
+    @staticmethod
+    def _public_item(item: dict[str, object]) -> dict[str, object]:
+        return {"path": str(item["path"]), "size": int(item["size"])}
+
+    def _scan_raw(self) -> list[dict[str, object]]:
+        videos = []
+        for directory, dirnames, filenames in os.walk(self.root):
+            dirnames.sort()
+            for filename in sorted(filenames):
+                path = Path(directory, filename)
+                if path.suffix.lower() not in VIDEO_EXTENSIONS:
+                    continue
+                try:
+                    stat = path.stat()
+                    relative = path.relative_to(self.root).as_posix()
+                except (OSError, ValueError):
+                    continue
+                videos.append(
+                    {"path": relative, "size": stat.st_size, "mtime_ns": stat.st_mtime_ns}
+                )
+        videos.sort(key=lambda item: str(item["path"]))
+        return videos
+
+    def _stable_after_delay(
+        self, items: list[dict[str, object]]
+    ) -> set[str]:
+        if not items:
+            return set()
+        if self.settle_seconds:
+            time.sleep(self.settle_seconds)
+        stable = set()
+        for item in items:
+            relative = str(item["path"])
+            path = self.root / PurePosixPath(relative)
+            try:
+                stat = path.stat()
+            except OSError:
+                continue
+            if (
+                stat.st_size == int(item["size"])
+                and stat.st_mtime_ns == int(item["mtime_ns"])
+            ):
+                stable.add(relative)
+        return stable
+
+    def _refresh_worker(self) -> None:
+        try:
+            with self.catalog_lock:
+                self.refreshing = True
+                self.last_scan_started = time.time()
+                old_items = {str(item["path"]): item for item in self.videos}
+                old_signatures = dict(self.signatures)
+
+            scanned = self._scan_raw()
+            changed = [
+                item
+                for item in scanned
+                if old_signatures.get(str(item["path"]))
+                != (int(item["size"]), int(item["mtime_ns"]))
+            ]
+            stable_changed = self._stable_after_delay(changed)
+
+            accepted = []
+            accepted_signatures: dict[str, tuple[int, int]] = {}
+            for item in scanned:
+                relative = str(item["path"])
+                signature = (int(item["size"]), int(item["mtime_ns"]))
+                if old_signatures.get(relative) == signature or relative in stable_changed:
+                    accepted.append(self._public_item(item))
+                    accepted_signatures[relative] = signature
+                elif relative in old_items:
+                    accepted.append(old_items[relative])
+                    accepted_signatures[relative] = old_signatures[relative]
+
+            accepted.sort(key=lambda item: str(item["path"]))
+            with self.catalog_lock:
+                catalog_changed = accepted != self.videos
+                self.videos = accepted
+                self.paths = {str(item["path"]) for item in accepted}
+                self.signatures = accepted_signatures
+                self.total_size = sum(int(item["size"]) for item in accepted)
+                if catalog_changed:
+                    self.revision += 1
+                self.last_scan_finished = time.time()
+                print(
+                    f"Catalog refresh complete: {len(self.videos)} videos "
+                    f"(revision {self.revision})",
+                    flush=True,
+                )
+        except Exception as error:
+            print(f"Catalog refresh failed: {error}", flush=True)
+        finally:
+            with self.catalog_lock:
+                self.refreshing = False
+                self.last_scan_finished = time.time()
+            self.refresh_guard.release()
+
+    def request_refresh(self) -> bool:
+        if not self.refresh_guard.acquire(blocking=False):
+            return False
+        with self.catalog_lock:
+            self.refreshing = True
+            self.last_scan_started = time.time()
+        threading.Thread(
+            target=self._refresh_worker,
+            name="video-catalog-refresh",
+            daemon=True,
+        ).start()
+        return True
+
+    def _auto_refresh_loop(self) -> None:
+        while True:
+            time.sleep(self.refresh_interval)
+            self.request_refresh()
+
+    def status(self) -> dict[str, object]:
+        with self.catalog_lock:
+            return {
+                "revision": self.revision,
+                "video_count": len(self.videos),
+                "total_size": self.total_size,
+                "refreshing": self.refreshing,
+                "last_scan_started": self.last_scan_started,
+                "last_scan_finished": self.last_scan_finished,
+                "refresh_interval": self.refresh_interval,
+            }
+
+    def catalog(self) -> dict[str, object]:
+        with self.catalog_lock:
+            result = {
+                "videos": list(self.videos),
+                "revision": self.revision,
+                "video_count": len(self.videos),
+                "total_size": self.total_size,
+                "refreshing": self.refreshing,
+                "last_scan_started": self.last_scan_started,
+                "last_scan_finished": self.last_scan_finished,
+                "refresh_interval": self.refresh_interval,
+            }
+        return result
+
+    def resolve_video(self, relative: str) -> Path | None:
+        normalized = PurePosixPath(relative).as_posix()
+        with self.catalog_lock:
+            known = normalized in self.paths
+        if not known:
+            return None
+        candidate = (self.root / normalized).resolve()
+        try:
+            candidate.relative_to(self.root)
+        except ValueError:
+            return None
+        return candidate if candidate.is_file() else None
+
+    def select(self, relative: str, slot: str) -> str:
+        token = secrets.token_urlsafe(24)
+        with self.lease_lock:
+            if slot not in self.leases and len(self.leases) >= 256:
+                self.leases.pop(next(iter(self.leases)))
+            self.leases[slot] = (relative, token)
+        return token
+
+    def release(self, slot: str, token: str) -> bool:
+        with self.lease_lock:
+            lease = self.leases.get(slot)
+            if lease is None or not secrets.compare_digest(token, lease[1]):
+                return False
+            del self.leases[slot]
+            return True
+
+    def is_active(self, relative: str, slot: str, token: str) -> bool:
+        with self.lease_lock:
+            lease = self.leases.get(slot)
+            return (
+                lease is not None
+                and relative == lease[0]
+                and secrets.compare_digest(token, lease[1])
+            )
+
+
+class VideoReviewHandler(BaseHTTPRequestHandler):
+    server_version = "HYVideoReview/1.0"
+
+    @property
+    def state(self) -> ReviewState:
+        return self.server.review_state  # type: ignore[attr-defined]
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        print(f"{self.address_string()} - {fmt % args}", flush=True)
+
+    def send_bytes(self, data: bytes, content_type: str, status: int = 200) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(data)
+
+    def send_json(self, value: object, status: int = 200) -> None:
+        self.send_bytes(
+            json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode(),
+            "application/json; charset=utf-8",
+            status,
+        )
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/":
+            self.send_bytes(INDEX_HTML.encode(), "text/html; charset=utf-8")
+        elif parsed.path == "/api/videos":
+            self.send_json(self.state.catalog())
+        elif parsed.path == "/api/status":
+            self.send_json(self.state.status())
+        elif parsed.path == "/media":
+            self.serve_media(parsed.query)
+        elif parsed.path == "/download":
+            self.serve_download(parsed.query)
+        elif parsed.path == "/healthz":
+            self.send_json({"ok": True, **self.state.status()})
+        else:
+            self.send_error(HTTPStatus.NOT_FOUND)
+
+    def do_HEAD(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/media":
+            self.serve_media(parsed.query)
+        elif parsed.path == "/download":
+            self.serve_download(parsed.query)
+        elif parsed.path == "/healthz":
+            self.send_json({"ok": True, "videos": len(self.state.videos)})
+        else:
+            self.send_error(HTTPStatus.NOT_FOUND)
+
+    def do_POST(self) -> None:
+        endpoint = urlparse(self.path).path
+        if endpoint == "/api/refresh":
+            started = self.state.request_refresh()
+            self.send_json({"started": started, **self.state.status()}, HTTPStatus.ACCEPTED)
+            return
+        if endpoint not in {"/api/select", "/api/release"}:
+            self.send_error(HTTPStatus.NOT_FOUND)
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+            if length > 64 * 1024:
+                raise ValueError("request too large")
+            payload = json.loads(self.rfile.read(length))
+            slot = str(payload["slot"])
+            if not slot or len(slot) > 128:
+                raise ValueError("invalid slot")
+        except (ValueError, KeyError, TypeError, json.JSONDecodeError):
+            self.send_json({"error": "invalid request"}, HTTPStatus.BAD_REQUEST)
+            return
+
+        if endpoint == "/api/release":
+            try:
+                token = str(payload["token"])
+            except (KeyError, TypeError):
+                self.send_json({"error": "invalid request"}, HTTPStatus.BAD_REQUEST)
+                return
+            self.send_json({"released": self.state.release(slot, token)})
+            return
+
+        try:
+            relative = str(payload["path"])
+        except (KeyError, TypeError):
+            self.send_json({"error": "invalid request"}, HTTPStatus.BAD_REQUEST)
+            return
+        if self.state.resolve_video(relative) is None:
+            self.send_json({"error": "video not found"}, HTTPStatus.NOT_FOUND)
+            return
+        self.send_json({"token": self.state.select(relative, slot)})
+
+    def serve_media(self, query: str) -> None:
+        params = parse_qs(query)
+        relative = params.get("path", [""])[0]
+        slot = params.get("slot", [""])[0]
+        token = params.get("token", [""])[0]
+        path = self.state.resolve_video(relative)
+        if path is None:
+            self.send_error(HTTPStatus.NOT_FOUND)
+            return
+        if not self.state.is_active(relative, slot, token):
+            self.send_error(HTTPStatus.GONE, "video lease expired")
+            return
+
+        size = path.stat().st_size
+        start, end = 0, size - 1
+        range_header = self.headers.get("Range")
+        if range_header:
+            match = re.fullmatch(r"bytes=(\d*)-(\d*)", range_header.strip())
+            if not match:
+                self.send_error(HTTPStatus.REQUESTED_RANGE_NOT_SATISFIABLE)
+                return
+            first, last = match.groups()
+            if first:
+                start = int(first)
+                end = min(int(last), size - 1) if last else size - 1
+            elif last:
+                suffix = int(last)
+                start = max(0, size - suffix)
+            if start >= size or end < start:
+                self.send_response(HTTPStatus.REQUESTED_RANGE_NOT_SATISFIABLE)
+                self.send_header("Content-Range", f"bytes */{size}")
+                self.end_headers()
+                return
+
+        length = end - start + 1
+        content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+        self.send_response(HTTPStatus.PARTIAL_CONTENT if range_header else HTTPStatus.OK)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(length))
+        self.send_header("Accept-Ranges", "bytes")
+        self.send_header("Cache-Control", "private, no-store")
+        if range_header:
+            self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+        self.end_headers()
+        if self.command == "HEAD":
+            return
+
+        remaining = length
+        try:
+            with path.open("rb") as source:
+                source.seek(start)
+                while remaining > 0 and self.state.is_active(relative, slot, token):
+                    chunk = source.read(min(CHUNK_SIZE, remaining))
+                    if not chunk:
+                        break
+                    self.wfile.write(chunk)
+                    remaining -= len(chunk)
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+
+    def serve_download(self, query: str) -> None:
+        relative = parse_qs(query).get("path", [""])[0]
+        path = self.state.resolve_video(relative)
+        if path is None:
+            self.send_error(HTTPStatus.NOT_FOUND)
+            return
+
+        size = path.stat().st_size
+        content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+        fallback = re.sub(r"[^A-Za-z0-9._-]", "_", path.name) or "video"
+        encoded = quote(path.name, safe="")
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(size))
+        self.send_header(
+            "Content-Disposition",
+            f'attachment; filename="{fallback}"; filename*=UTF-8\'\'{encoded}',
+        )
+        self.send_header("Cache-Control", "private, no-store")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.end_headers()
+        if self.command == "HEAD":
+            return
+
+        try:
+            with path.open("rb") as source:
+                while chunk := source.read(CHUNK_SIZE):
+                    self.wfile.write(chunk)
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+
+
+class ReviewServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address: tuple[str, int], state: ReviewState):
+        super().__init__(address, VideoReviewHandler)
+        self.review_state = state
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1])
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--refresh-interval", type=float, default=DEFAULT_REFRESH_INTERVAL)
+    parser.add_argument("--settle-seconds", type=float, default=DEFAULT_SETTLE_SECONDS)
+    args = parser.parse_args()
+
+    state = ReviewState(args.root, args.refresh_interval, args.settle_seconds)
+    server = ReviewServer((args.host, args.port), state)
+    print(
+        f"Reviewing {len(state.videos)} videos under {state.root}\n"
+        f"Listening on http://{args.host}:{args.port}\n"
+        f"Auto-refresh every {state.refresh_interval:g}s; "
+        f"new files settle for {state.settle_seconds:g}s",
+        flush=True,
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()

train.md

@@ -0,0 +1,592 @@
+# Train
+
+## 实验命名规范
+
+从 2026-07-22 起，checkpoint 目录、独立日志、SwanLab experiment 和评测输出统一显式记录两组
+学习率、训练总步数与两种 warmup：
+
+```text
+<experiment>_flr<fusion_lr>_blr<blocks_lr>_schedsteps<max_steps>_swarmup<scheduler_warmup>_bwarmup<block_warmup>
+```
+
+- `flr`：image fusion/residual 参数组的峰值学习率；
+- `blr`：两个 Predictor blocks 参数组的峰值学习率；
+- `schedsteps`：创建 LR scheduler 时使用的训练总步数，不代表某次运行实际走到的步数；
+- `swarmup`：全局 cosine scheduler 的 warmup steps；
+- `bwarmup`：blocks 参数组额外冻结/延迟启用的 warmup steps；旧 rollout 没有该独立参数时写
+  `bwarmup-none`；
+- `ckptstep`：仅用于评测输出，表示本次评测实际加载的 checkpoint step。
+
+例如，计划训练 2000 steps、实际使用 step 300 权重进行评测时，训练目录保留
+`schedsteps2000`，评测目录同时写 `ckptstep300` 与 `schedsteps2000`。目录内的 `train_log.jsonl`、
+`torchrun.log`、`train_config.json` 和 `swanlab/` 不重复拼接参数，它们继承父目录的完整命名。
+
+当前主要配置如下：
+
+| 实验组 | `flr` | `blr` | `schedsteps` | `swarmup` | `bwarmup` |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| v4 / predictor-disca 离线 Stage 1 | 1e-4 | 1e-5 | 2000 | 100 | 100 |
+| 早期整轨迹 FPPP rollout | 1e-5 | 1e-6 | 2000 | 50 | none |
+| overfit8 FPPP rollout | 1e-4 | 1e-5 | 2000 | 8 | 8 |
+| overfit8 FPPF rollout | 1e-4 | 1e-5 | 300 | 8 | 8 |
+| 旧 timestep-only sweep | 1e-4 | 1e-5 | 200 | 8 | 8 |
+| detached timestep-only | 1e-4 | 1e-5 | 1000 | 8 | 8 |
+
+## 1. 监督目标
+
+当前 v4 数据为每个 chunk 保存四步 Full-DiT Teacher hidden 和 velocity。正式 v4 与
+predictor-disca 使用全部相邻监督 pair：
+
+```text
+step 0 final hidden + step 1 input -> step 1 hidden / velocity
+step 1 final hidden + step 2 input -> step 2 hidden / velocity
+step 2 final hidden + step 3 input -> step 3 hidden / velocity
+```
+
+v1/v2/v3 的历史训练只使用 `0→1` 和 `2→3`，对应 F-P-F-P；从 v4 开始加入 `1→2`，使 Predictor
+具备连续替代和任意选择后三步的能力。
+
+## 2. Loss
+
+所有版本使用相同的监督损失：
+
+```python
+hidden_loss = mse(pred_hidden.float(), target_hidden.float())
+velocity_loss = mse(pred_velocity.float(), target_velocity.float())
+loss = 0.1 * hidden_loss + 1.0 * velocity_loss
+```
+
+- hidden 和 velocity 的 forward 使用 BF16；
+- MSE 转为 FP32 计算；
+- velocity MSE 是主目标；
+- hidden MSE 是 final-layer 前 feature 的辅助约束；
+- frozen final layer 只冻结参数，forward 不能放进 `no_grad()`，否则 velocity loss 无法回传到
+  Predictor hidden。
+
+## 3. 优化方法
+
+当前正式训练使用 AdamW：
+
+| 参数组 | 学习率 |
+| --- | ---: |
+| image fusion + residual head | 1e-4 |
+| 两个 Predictor blocks | 1e-5 |
+
+共同配置：
+
+```yaml
+betas: [0.9, 0.95]
+weight_decay: 0.01
+grad_clip: 1.0
+precision: bfloat16
+loss_precision: float32
+max_steps: 2000
+scheduler: cosine
+scheduler_warmup_steps: 100
+block_warmup_steps: 100
+gradient_checkpointing: true
+```
+
+前 100 optimizer steps 中 Predictor block 参数组的学习率为 0，只训练 fusion/residual；之后 block
+组按较低学习率参与训练。两个参数组都经过 100-step warmup 和 cosine decay，step 2000 衰减到 0。
+
+## 4. 各版本训练方式
+
+### v1
+
+- 入口：`train_predictor.py`；
+- 单 GPU、micro-batch 1；
+- gradient accumulation 4，有效 batch 4；
+- 2000 steps；
+- pairs：`0→1`、`2→3`；
+- source blocks：`[1,52]`；
+- 每 500 steps 保存，默认保留 2 个快照。
+
+旧机器上的 v1 实验结果不再纳入当前文档，这里只保留训练方法。
+
+### v2/v3
+
+- 入口：`train_predictor_v2.py --predictor_version v2|v3`；
+- 单 GPU，默认 batch 1、gradient accumulation 4；
+- pairs：`0→1`、`2→3`；
+- source blocks：`[0,53]` 或 `[1,52]`；
+- 2000 steps、100-step block warmup；
+- SwanLab 可选。
+
+v3 Dataset 额外加载前一 chunk 的 target-step final hidden，并排除 chunk 0。迁移后的当前目录未保留
+v2/v3 正式 checkpoint，因此这里只记录方法，不将缺失产物写成可复现实验结果。
+
+### v4
+
+- 入口：`train_predictor_v4.py`；
+- 启动：`tools/launch_predictor_v4_training.sh`；
+- 8 卡 DDP；
+- 每卡 batch size 16，全局 batch size 128；
+- gradient accumulation 1；
+- 2800 records × 3 transitions = 8400 pairs；
+- 按 Context frames 分桶，减少动态 padding；
+- 2000 steps；
+- 每 100 steps 保存，保留 20 个 safetensors；
+- SwanLab 仅由 rank 0 上报。
+
+已训练 blocks `[0,53]` 和 `[1,52]` 两版。
+
+### predictor-disca
+
+- 入口：`train_predictor_disca.py`；
+- 启动：`tools/launch_predictor_disca_training.sh`；
+- 8 卡 DDP、每卡 batch size 16、全局 batch size 128；
+- 8400 pairs、2000 steps；
+- 不加载 Context pre-feature 或 previous-chunk hidden；
+- 不按 Context frames 分桶，使用普通 DistributedSampler；
+- 每 100 steps 保存，保留 20 个 safetensors；
+- 当前正式版使用 blocks `[0,53]`。
+
+## 5. 当前正式训练结果
+
+下表是训练日志在 step 2000 记录窗口内的均值，不是完整数据集 validation loss：
+
+| 版本 | blocks | total loss | hidden MSE | velocity MSE | peak memory/GPU | avg micro time |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| v4 | `[0,53]` | 0.011895 | 0.011744 | 0.010721 | 62.82 GiB | 4.47 s |
+| v4 | `[1,52]` | 0.011537 | 0.011732 | 0.010364 | 62.82 GiB | 4.49 s |
+| predictor-disca | `[0,53]` | 0.011053 | 0.011121 | 0.009941 | 31.18 GiB | 1.66 s |
+
+训练 loss 不能直接替代 rollout 视频质量。predictor-disca 的训练 loss 更低，但其训练集视频指标明显
+低于 v4，说明缺失 AR Context 后更容易拟合单步监督，却在连续在线 rollout 中累积了更大误差。
+
+## 6. Checkpoint 与 resume
+
+正式训练同时保存：
+
+```text
+predictor_step_XXXXX.safetensors   # 仅模型推理权重
+training_latest.pt                 # model、optimizer、scheduler、step、epoch、配置
+train_config.json
+train_log.jsonl
+torchrun.log
+swanlab/
+```
+
+resume 会恢复 model、optimizer、scheduler、global/micro step 和 epoch，并检查 source blocks 与
+Predictor variant 是否匹配。例如：
+
+```bash
+python train_predictor_disca.py \
+  --resume checkpoints/predictor_disca_blocks0-53_bf16_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/training_latest.pt
+```
+
+正式云端监控使用：
+
+```bash
+export SWANLAB_API_KEY='<token>'
+```
+
+token 只放在进程环境或用户登录缓存中，不写入仓库、配置或日志。
+
+## 7. 在线训练集评测
+
+统一评测 100 个训练 case × 4 actions，共 400 个 125-frame 视频：
+
+```text
+reference: Full-DiT F-F-F-F
+reuse:     Full steps 0、3；steps 1、2 reuse
+predictor: Full steps 0、3；steps 1、2 Predictor
+```
+
+视频指标包括 full-resolution PSNR、frame-mean PSNR、SSIM、AlexNet LPIPS、pixel
+MSE/RMSE/MAE 和 temporal-delta MSE。
+
+| 方法 | blocks | PSNR | SSIM | LPIPS | temporal delta MSE |
+| --- | --- | ---: | ---: | ---: | ---: |
+| Direct Reuse | — | 18.4639 | 0.6429 | 0.2083 | 0.01212 |
+| v4 | `[0,53]` | 21.9337 | 0.7606 | 0.1204 | 0.00865 |
+| v4 | `[1,52]` | 22.1090 | 0.7670 | 0.1168 | 0.00832 |
+| predictor-disca | `[0,53]` | 19.4084 | 0.6748 | 0.1816 | 0.01061 |
+
+这些是 train-set/in-sample 指标，只能比较架构在已训练图文 pair 上的拟合和 rollout 行为，不能证明
+对新图、新 prompt、新 seed 或新动作的泛化。validation/test 应使用 `data.md` 中互斥的 25/50 pair
+holdout。
+
+## 8. v4 递归 F-P-P-P Self-Rollout 微调方案
+
+### 8.1 定位与实现状态
+
+这是一阶段离线 Teacher-forcing 训练之后的二阶段 rollout 微调。初始化应加载已有 v4 Predictor
+权重，而不是重新从两个 Teacher blocks 开始训练。当前训练集视频结果中 `[1,52]` 最好，因此正式
+实验优先从以下离线 v4 FP32-master 训练状态中的 `model` 初始化；optimizer/scheduler 不继承，
+rollout 使用全新的优化状态：
+
+```text
+checkpoints/predictor_v4_prefeature_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/training_latest.pt
+```
+
+`[0,53]` 可以用同一套流程作为独立对照，但 source blocks 必须与初始 checkpoint 一致。rollout
+训练已作为独立入口实现，不改变现有离线 `train_predictor_v4.py`：
+
+```text
+train_predictor_v4_rollout.py
+predictor_training/trajectory_dataset.py
+predictor_training/rollout_utils.py
+tools/launch_predictor_v4_rollout_training.sh
+```
+
+低学习率 `[1,52]` 基线输出到以下目录，并已按实验要求在 step 600 停止：
+
+```text
+checkpoints/predictor_v4_rollout_fppp_blocks1-52_fp32master_8gpu_flr1e-5_blr1e-6_schedsteps2000_swarmup50_bwarmup-none_swanlab
+```
+
+使用第一阶段学习率的正式入口改用明确 LR 命名，避免用含义模糊的 `stage1lr`：
+
+```text
+checkpoints/predictor_v4_rollout_fppp_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab
+```
+
+### 8.2 目标轨迹
+
+每条 item 是一个完整的 `(case_id, action_id)` trajectory，而不是一个独立 transition：
+
+```text
+Chunk 0：F-F-F-F，只建立 self-generated history 和 previous-chunk hidden，不训练
+Chunk 1～7：F-P-P-P，三个 Predictor step 都计算 loss
+```
+
+在训练 chunk 内：
+
+```text
+initial x0
+  -> Full step 0: h0, v0
+  -> Euler update: x1
+  -> Predictor step 1: pred_h1, pred_v1
+  -> differentiable Euler update: x2
+  -> Predictor step 2: pred_h2, pred_v2
+  -> differentiable Euler update: x3
+  -> Predictor step 3: pred_h3, pred_v3
+  -> differentiable Euler update: final chunk latent
+```
+
+同一 chunk 内 `pred_h1 → pred_h2 → pred_h3` 是递归 same-chunk anchor，三个 Predictor 调用保留
+一张完整计算��。chunk 之间则同时 detach：
+
+- final chunk latent detach 后加入 history；
+- `pred_h1/pred_h2/pred_h3` detach 后作为下一 chunk 的同 step previous-chunk hidden。
+
+因此，v4 的 previous-chunk 输入不能只用最终 latent 代替。Chunk 0 虽不训练，也必须保存 Full-DiT
+step 1、2、3 的 final hidden，分别作为 Chunk 1 Predictor step 1、2、3 的 previous-chunk hidden。
+
+### 8.3 轻量样本表与全在线构建
+
+Self-rollout 不依赖之前构建的 F-F-F-F tensor 数据集。Dataset 只保存一张轻量样本表，每个 item
+包含：
+
+```text
+case_id, source_image, caption, action_id, pose, seed
+```
+
+100 个图文 pair × 4 actions 组成 400 条 trajectory。`__getitem__` 不读取 step tensor、Teacher
+hidden/velocity、Context pre-feature 或 K/V；每个 rank 拿到样本描述后，使用当前正式 WorldPlay
+pipeline 在线完成：
+
+1. 按与数据构建/评测相同的规则将输入图像 resize/crop 到 480×832；
+2. 使用 `pose_to_input(pose, 32)` 生成完整 8-chunk viewmats、Ks 和 action；
+3. 用指定 seed 调用 `prepare_latents`，一次生成 `[1,32,32,30,52]` 初始噪声，再按 4 latent
+   frames 切成 8 个 chunk；
+4. 从现有 case tensor 读取静态 `image_condition_latent`，在线构造 condition/mask，避免重复 VAE
+   encode；
+5. 从离线数据集的 `text_kv_exact_all54_bf16/` 读取全部 54 层精确 BF16 Text K/V，并按
+   `text_valid_mask` 去掉磁盘 padding；
+6. 从 Chunk 0 开始在线执行整条 F-F-F-F/F-P-P-P trajectory，并在线生成所有监督 target。
+
+每一步仍按当前 pipeline 语义构造 65 通道输入：32 通道 current noisy latent 加 32 通道 image
+condition 和 1 通道 mask。只有 Chunk 0 的第一个 latent frame 含 image condition；Chunk 1～7 的
+33 个 condition 通道为零。history prefill 同样拼接对应历史帧的固定 condition，不能只把 32 通道
+self latent 送入 Teacher。
+
+因此 rollout 训练不读取或生成持久化的 `step_1/2/3_noisy_sample`、Teacher target、Context
+pre-feature、previous-step hidden 或全层 Text K/V sidecar。Text K/V 与 Predictor policy 和 trajectory
+状态无关，按 case 存在主离线数据集内；所有 policy-dependent 状态仍在当前参数、当前 self history 上
+产生，语义是严格 on-policy。图像/caption/action 样本表不是 Teacher trajectory 数据，可以直接从
+当前 100 个训练 pair 的来源清单生成；留出集不参与训练。
+
+静态 Text K/V 构建时来自 prompt、vision 和 ByT5 编码，训练主循环不再加载这三个编码器，也不再
+重复 text prefill。
+
+### 8.4 v4 Context 的准确语义
+
+每个 chunk 使用当前 detached、self-generated history 运行与正式推理相同的
+`select_aligned_memory_frames`。选择结果只由相机轨迹决定；被选中的 latent 内容必须来自当前
+self history。
+
+随后冻结 Full Teacher 对这些 history latent 执行一次 54-layer AR vision prefill，得到精确 Context
+Vision K/V。该 cache：
+
+- 与当前 trajectory 的全层 Text K/V 合并；
+- 在当前 chunk 的四个 denoise steps 间只读共享；
+- Teacher target 使用全部 54 层 cache；
+- v4 Predictor 直接读取其 source blocks 对应的同一份 exact K/V；
+- 全部 detach，且不对 Context 建图。
+
+这里不走 `context_prefeature -> frozen projector -> K/V` 路径。pre-feature 是离线 pair 训练的磁盘
+压缩方案；在线 rollout 已经由 Teacher prefill 持有 exact K/V，行为应与当前推理 pipeline 一致。
+
+### 8.5 单个 chunk 的 Teacher 与 Predictor 顺序
+
+Chunk 0 在 `torch.no_grad()` 下执行四次 Full-DiT，并保存 final latent 和 Full hidden-by-step。
+Chunk 1～7 的顺序固定为：
+
+1. 从 detached history 选择 Context，并由 Teacher 生成 exact AR K/V；
+2. Full Teacher 在 step 0 输入上产生 `h0/v0`，用正式 Euler scheduler 更新到 `x1`；
+3. 对 step 1～3，先在 `current_student_latent.detach()` 上运行 Full Teacher，获得
+   `target_hidden/target_velocity`；
+4. Predictor 使用相同 noisy latent、condition、相机参数和 Context K/V；
+5. step 1 的 anchor 是 `h0`，step 2 是 `pred_h1`，step 3 是 `pred_h2`；
+6. 每个 Predictor velocity 经可微 scheduler 更新到下一 latent；
+7. 三步 loss 求均值，当前 chunk 立即 backward；
+8. final latent 与三步 pred hidden detach 后加入下一 chunk 状态。
+
+Teacher target 必须来自 Predictor 真正访问的状态。对应当前 Transformer API 的核心调用是：
+
+```python
+with torch.no_grad():
+    teacher_model_input = torch.cat(
+        [current_student_latent.detach(), current_condition_33ch], dim=1
+    )
+    teacher_output = full_teacher(
+        bi_inference=False,
+        ar_txt_inference=False,
+        ar_vision_inference=True,
+        hidden_states=teacher_model_input,
+        timestep=current_timestep,
+        timestep_r=None,
+        mask_type=task_type,
+        action=current_action,
+        viewmats=current_viewmats,
+        Ks=current_Ks,
+        kv_cache=exact_context_kv,
+        cache_vision=False,
+        rope_temporal_size=rope_temporal_size,
+        start_rope_start_idx=start_rope_start_idx,
+        return_final_hidden=True,
+    )
+    target_velocity = teacher_output[0]
+    target_hidden = teacher_output[2]
+```
+
+不能读取原 F-F-F-F trajectory 中相同步的 target。Teacher 只用于构造 stop-gradient label，其输出
+立即释放。Predictor 使用的 `target_frame_condition` 继续由冻结 Teacher 的
+`time_in(timestep) + action_in(action)` 计算，不从旧 target 文件推断。
+
+### 8.6 完整 timestep BPTT 的代码前置条件
+
+当前 `HYWorldPlayPredictorV2.forward`（v4 继承该实现）使用 `torch.no_grad()` 包裹冻结 `img_in`。
+这会阻断 `x2/x3 -> img_in -> Predictor` 的输入梯度，不满足完整 timestep BPTT。rollout 实现前必须
+改为：
+
+```python
+# img_in 参数保持 requires_grad=False，但 forward 不进入 no_grad。
+current_img = self.img_in(target_model_input)
+```
+
+冻结参数不会产生 parameter gradient；当离线训练输入不需要梯度时也不会额外建图，但 rollout 的
+step 2、3 可以对前一步 scheduler 输出求导。冻结 final layer 同理：参数不训练，forward 仍必须保留
+对 `pred_hidden` 的梯度。Context projector 保持 `no_grad()`，因为 Context 本来就应 detach。
+
+### 8.7 可微 FlowMatch Euler update
+
+当前项目的 `FlowMatchDiscreteScheduler.step` 在 `solver=euler` 时核心公式已经是 out-of-place 且可微：
+
+```python
+x_next = x.float() + pred_velocity.float() * (
+    sigmas[step_index + 1] - sigmas[step_index]
+)
+```
+
+但正式 pipeline 会把结果原位写回共享 `latents`，不应直接复制该容器逻辑。训练应实现无状态的
+`differentiable_euler_step`：调用相同 `set_timesteps(4)` 后读取同一组 sigmas，每次只接收和返回当前
+chunk local tensor，无 `detach`、`no_grad` 或 inplace slice assignment。其 FP32 update 和输出 dtype
+必须与正式 scheduler 数值一致。
+
+step 2、3 的 loss 应同时通过两类路径影响前面的 Predictor 调用：
+
+```text
+hidden anchor path: pred_h1 -> Predictor step 2 -> pred_h2 -> Predictor step 3
+latent path:        pred_v1 -> x2 -> Predictor step 2 -> pred_v2 -> x3 -> Predictor step 3
+```
+
+### 8.8 Loss 与归一化
+
+每个 Predictor step 继续使用 v4 的 FP32 MSE：
+
+```python
+step_loss = (
+    mse(pred_velocity.float(), target_velocity.float())
+    + 0.1 * mse(pred_hidden.float(), target_hidden.float())
+)
+chunk_loss = (step1_loss + step2_loss + step3_loss) / 3
+```
+
+一条 trajectory 有七个训练 chunk，所以每个 chunk 执行：
+
+```python
+(chunk_loss / 7).backward()
+```
+
+不要再除以 world size，DDP 会对 8 个 rank 自动求平均。若以后额外累计多条 trajectory 才更新一次，
+还需要再除以 `gradient_accumulation_trajectories`。日志应分别记录 step 1/2/3 hidden MSE、velocity
+MSE、chunk id 均值和整条 trajectory loss，不能只记录合并 total loss。
+
+### 8.9 8 卡 DDP 与同步边界
+
+每个 rank 持有一份冻结的 54-layer Teacher、一份 DDP v4 Predictor 和一条独立 trajectory。只包装
+Predictor：
+
+```python
+predictor = DDP(
+    predictor,
+    device_ids=[local_rank],
+    output_device=local_rank,
+    broadcast_buffers=False,
+    gradient_as_bucket_view=True,
+    find_unused_parameters=False,
+)
+```
+
+400 条 trajectory 可被 8 个 rank 整除。`DistributedSampler(..., drop_last=True)` 每个 epoch 给每个
+rank 50 条，调用 `sampler.set_epoch(epoch)` 保证 shuffle 一致且不同 rank 不重叠。micro-batch 固定为
+每卡一条 trajectory，因此每个 optimizer step 的全局 batch 是 8 trajectories。
+
+Chunk 1～6 只累计本地梯度，Chunk 7 backward 时执行一次 all-reduce：
+
+```python
+optimizer.zero_grad(set_to_none=True)
+
+for chunk_id in range(1, 8):
+    sync_ctx = nullcontext() if chunk_id == 7 else predictor.no_sync()
+    with sync_ctx:  # 必须同时覆盖三个 DDP forward 和当前 backward
+        chunk_loss, final_latent, hidden_by_step = train_fppp_chunk(...)
+        (chunk_loss / 7).backward()
+
+    history.append(final_latent.detach())
+    previous_hidden_by_step = {
+        step: hidden.detach() for step, hidden in hidden_by_step.items()
+    }
+    del chunk_loss, final_latent, hidden_by_step
+
+clip_grad_norm_(predictor.parameters(), 1.0)
+optimizer.step()
+lr_scheduler.step()
+```
+
+七个 chunk 中间不能 `optimizer.step()` 或 `zero_grad()`。现有 Predictor checkpoint 使用
+`use_reentrant=False`，应继续保留；三个 DDP forward 合并一次 backward 以及七次 chunk backward 的
+组合必须先通过单卡/DDP 小规模梯度一致性测试。
+
+### 8.10 显存与训练配置
+
+每个 rank 加载 Transformer Teacher 和 Predictor。image-condition latent 直接从 case tensor 读取；
+全层 Text K/V 从主离线数据集读取并去掉 padding。训练不加载 prompt encoder、vision encoder、
+ByT5、VAE、SR 或视频编码组件。可微 rollout 阶段只让 Teacher、Predictor、当前 Text/Context cache
+和当前 chunk graph 驻留 GPU。
+
+Teacher 全程 eval、`requires_grad_(False)` 和 `no_grad()`；Predictor forward activation 使用 BF16
+autocast，所有可训练 Predictor 参数及 AdamW moments 保持 FP32，loss 使用 FP32，并开启现有
+non-reentrant gradient checkpointing。冻结参数和 Teacher 权重仍为 BF16。每个 chunk backward 后
+立即释放三步图，history、previous hidden 和 Context K/V 全部 detach。
+
+checkpoint 分成两种精度语义：`training_latest.pt` 保留 FP32 trainable master 参数、FP32 optimizer
+状态和 scheduler，用于无损 resume；`predictor_step_XXXXX.safetensors` 显式转换为 BF16，只用于推理
+和评测。resume 时会检查 checkpoint 的 FP32-master 配置，禁止把旧 BF16 rollout optimizer 静默载入
+当前训练。
+
+建议从已有 v4 权重开始一个全新的 optimizer/scheduler，不加载 Teacher-forcing
+`training_latest.pt` 中的 optimizer 状态。rollout checkpoint 自身仍保存 model、optimizer、scheduler、
+global optimizer step、epoch 和 sampler/trajectory 进度，并每 100 optimizer steps 保存一次。
+
+低学习率基线采用 fusion/residual `1e-5`、blocks `1e-6` 和 50-step warmup，运行至 step 600 后，
+完整 epoch mean loss 只下降约 3%，因此停止。后续正式配置改为与第一阶段相同的 LR 策略：
+fusion/residual 峰值 `1e-4`，blocks 峰值 `1e-5`；fusion 前 100 steps warmup，blocks 前 100 steps
+学习率为 0，之后两组共同 cosine decay 到 step 2000。这里的一个 step 指完整 8-rank trajectory
+更新，不是一个 chunk。
+
+每 100 steps 保存一次 checkpoint。训练入口持续断言每步 8 个 rank 的 trajectory 主键互异，并检查
+step 2/3 中间 latent 的梯度非零。
+
+正式启动前的 8 卡完整 8-chunk smoke test 已通过：fresh step 1 的 loss 为 `0.013256`，
+`latent_grad_l1_min=1.63e-4`，峰值显存 `49.13 GiB/GPU`；从该 checkpoint resume 到 step 2 后，
+`latent_grad_l1_min=2.98e-4`，峰值显存 `50.60 GiB/GPU`。训练 checkpoint 中 48 个可训练参数张量及
+Adam moments 均为 FP32，推理 safetensors 中 80 个张量均为 BF16。
+
+为区分学习率问题与梯度/模型容量问题，另固定随机种子 `20260721` 从 100 个训练 case 中选择
+`[4,11,17,28,58,80,94,96]`，每个 case 保留四种 action，共 32 条 trajectory。8 卡每个 epoch
+恰好 4 steps；临时将 fusion warmup 和 block freeze 都缩短为 8 steps，LR 仍为 `1e-4/1e-5`。
+截至 epoch 5，完整 overfit mean loss 从 `0.01969` 降至 `0.01836`，下降约 6.8%，证明递归梯度链路
+和优化器能够学习。该实验输出到：
+
+```text
+checkpoints/predictor_v4_rollout_fppp_blocks1-52_overfit8_seed20260721_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup8_bwarmup8_swanlab
+```
+
+### 8.11 分阶段验收
+
+实现必须依次通过：
+
+1. Dataset 只有 400 条互异的 `(case_id, action_id)` 元数据，8 个 rank 每步读取不同主键；
+2. Chunk 0 全部由 Full Teacher 计算、无参数梯度，并产生 step 1/2/3 previous hidden；
+3. step 2 anchor 与 `pred_h1`、step 3 anchor 与 `pred_h2` 数值和对象来源正确；
+4. 每个 Teacher target 的输入等于当前 student latent 的 detached copy，不读取任何离线 FFFF 状态；
+5. self history 生成的 Context latent 正确，selected indices 与正式推理函数一致；
+6. 训练 Euler update 与正式 `FlowMatchDiscreteScheduler.step` 在四个 step 上误差满足 FP32 容差；
+7. 只保留 step 3 loss 时，`x2/x3.grad` 非零，且前两次 Predictor 调用对参数有非零贡献；
+8. Chunk 2 loss 不会回传到 Chunk 1 final latent 或 previous hidden；
+9. Chunk 1～6 不触发 all-reduce，Chunk 7 每个 optimizer step 只同步一次；
+10. 单卡小样本中，分 chunk backward 与保留七个 chunk 后一次 backward 的梯度在容差内一致；
+11. 先完成 1-trajectory forward、1-step backward、8 卡 2-step DDP smoke test，再做 20-step overfit；
+12. 无 NaN/Inf，step 1/2/3 loss 均能下降，显存峰值有日志记录。
+
+最终评测必须使用 Chunk 0 `F-F-F-F`、Chunk 1～7 `F-P-P-P`，即
+`replace_steps=(1,2,3)`。在同一训练集和 25/50 holdout 上对比：Full-DiT、Direct Reuse、rollout
+微调前 v4 checkpoint 和微调后 checkpoint，并同时报告视频质量、端到端耗时和组件耗时。只有留出集
+F-P-P-P 优于微调前权重，才能说明 self-rollout 微调带来泛化收益。
+
+## 9. 训练入口速查
+
+v4：
+
+```bash
+bash tools/launch_predictor_v4_training.sh
+```
+
+v4 F-P-P-P on-policy rollout：
+
+```bash
+bash tools/launch_predictor_v4_rollout_training.sh
+```
+
+resume：
+
+```bash
+bash tools/launch_predictor_v4_rollout_training.sh \
+  checkpoints/predictor_v4_rollout_fppp_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab \
+  checkpoints/predictor_v4_rollout_fppp_blocks1-52_fp32master_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/training_latest.pt
+```
+
+8-case overfit：
+
+```bash
+bash tools/launch_predictor_v4_rollout_overfit8_training.sh
+```
+
+predictor-disca `[1,52]`：
+
+```bash
+bash tools/launch_predictor_disca_training.sh
+```
+
+predictor-disca `[0,53]`：
+
+```bash
+bash tools/launch_predictor_disca_training.sh \
+  checkpoints/predictor_disca_blocks0-53_bf16_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab \
+  0,53
+```

train_predictor.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Single-GPU training for the dense image/text HY-WorldPlay Predictor."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import random
+import time
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+from torch.optim import AdamW
+from torch.optim.lr_scheduler import LambdaLR
+from torch.utils.data import DataLoader
+
+from hyvideo.commons.infer_state import initialize_infer_state
+from models import HYWorldPlayPredictor
+from predictor_training.checkpoint import (
+    load_predictor_weights,
+    save_predictor_weights,
+    save_training_state,
+    trainable_state_dict,
+)
+from predictor_training.dataset import (
+    PredictorPairDataset,
+    move_pair_to_device,
+    predictor_collate,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", default="datasets/predictor_v1/train_eval_manifest.jsonl")
+    parser.add_argument(
+        "--teacher_checkpoint",
+        default="models-ms/HY-WorldPlay/ar_distilled_action_model/diffusion_pytorch_model.safetensors",
+    )
+    parser.add_argument(
+        "--output_dir",
+        default=(
+            "checkpoints/predictor_v1_blocks1-52_bf16_1gpu_"
+            "flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100"
+        ),
+    )
+    parser.add_argument("--max_steps", type=int, default=2000)
+    parser.add_argument("--gradient_accumulation_steps", type=int, default=4)
+    parser.add_argument("--warmup_blocks_steps", type=int, default=100)
+    parser.add_argument("--scheduler_warmup_steps", type=int, default=100)
+    parser.add_argument("--fusion_lr", type=float, default=1e-4)
+    parser.add_argument("--blocks_lr", type=float, default=1e-5)
+    parser.add_argument("--weight_decay", type=float, default=0.01)
+    parser.add_argument("--hidden_weight", type=float, default=0.1)
+    parser.add_argument("--velocity_weight", type=float, default=1.0)
+    parser.add_argument("--grad_clip", type=float, default=1.0)
+    parser.add_argument("--log_every", type=int, default=10)
+    parser.add_argument("--save_every", type=int, default=500)
+    parser.add_argument("--keep_snapshots", type=int, default=2)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--num_workers", type=int, default=0)
+    parser.add_argument("--max_records", type=int, default=None)
+    parser.add_argument("--gradient_checkpointing", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--save_optimizer_state", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--resume", default=None)
+    return parser.parse_args()
+
+
+def initialize_runtime_state() -> None:
+    class Args:
+        sage_blocks_range = "0-53"
+        use_sageattn = False
+        enable_torch_compile = False
+        use_fp8_gemm = False
+        quant_type = "fp8-per-block"
+        include_patterns = "double_blocks"
+        use_vae_parallel = False
+
+    initialize_infer_state(Args())
+
+
+def make_scheduler(optimizer: torch.optim.Optimizer, warmup: int, total: int) -> LambdaLR:
+    def factor(step: int) -> float:
+        if step < warmup:
+            return max(1e-8, float(step + 1) / max(1, warmup))
+        progress = min(1.0, float(step - warmup) / max(1, total - warmup))
+        return 0.5 * (1.0 + math.cos(math.pi * progress))
+
+    return LambdaLR(optimizer, factor)
+
+
+def set_blocks_trainable(model: HYWorldPlayPredictor, enabled: bool) -> None:
+    model.double_blocks.requires_grad_(enabled)
+
+
+def prune_snapshots(output_dir: Path, keep: int) -> None:
+    snapshots = sorted(output_dir.glob("predictor_step_*.safetensors"))
+    for path in snapshots[:-keep] if keep > 0 else snapshots:
+        path.unlink()
+
+
+def main() -> None:
+    args = parse_args()
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required")
+    random.seed(args.seed)
+    torch.manual_seed(args.seed)
+    torch.cuda.manual_seed_all(args.seed)
+    initialize_runtime_state()
+    device = torch.device("cuda:0")
+    dtype = torch.bfloat16
+    output_dir = Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    log_path = output_dir / "train_log.jsonl"
+
+    dataset = PredictorPairDataset(args.manifest, max_records=args.max_records)
+    generator = torch.Generator().manual_seed(args.seed)
+    loader = DataLoader(
+        dataset,
+        batch_size=1,
+        shuffle=True,
+        num_workers=args.num_workers,
+        pin_memory=True,
+        collate_fn=predictor_collate,
+        generator=generator,
+    )
+
+    model = HYWorldPlayPredictor()
+    model.load_teacher_initialization(args.teacher_checkpoint)
+    model.to(device=device, dtype=dtype)
+    model.enable_gradient_checkpointing(args.gradient_checkpointing)
+    model.train()
+
+    optimizer = AdamW(
+        [
+            {
+                "params": list(model.img_fusion.parameters())
+                + list(model.txt_fusion.parameters())
+                + list(model.residual_out.parameters()),
+                "lr": args.fusion_lr,
+            },
+            {"params": model.double_blocks.parameters(), "lr": args.blocks_lr},
+        ],
+        betas=(0.9, 0.95),
+        weight_decay=args.weight_decay,
+    )
+    scheduler = make_scheduler(optimizer, args.scheduler_warmup_steps, args.max_steps)
+    global_step = 0
+    micro_step = 0
+    set_blocks_trainable(model, args.warmup_blocks_steps <= 0)
+
+    if args.resume:
+        state = torch.load(args.resume, map_location="cpu", weights_only=False)
+        model.load_state_dict(state["model"], strict=False)
+        optimizer.load_state_dict(state["optimizer"])
+        scheduler.load_state_dict(state["scheduler"])
+        global_step = int(state["global_step"])
+        micro_step = int(state.get("micro_step", global_step * args.gradient_accumulation_steps))
+        if "torch_rng_state" in state:
+            torch.set_rng_state(state["torch_rng_state"])
+        if "cuda_rng_state" in state:
+            torch.cuda.set_rng_state_all(state["cuda_rng_state"])
+        set_blocks_trainable(model, global_step >= args.warmup_blocks_steps)
+
+    print(
+        json.dumps(
+            {
+                "dataset_pairs": len(dataset),
+                "trainable_parameters": model.trainable_parameter_count(),
+                "breakdown": model.trainable_parameter_breakdown(),
+                "start_step": global_step,
+            },
+            indent=2,
+        ),
+        flush=True,
+    )
+
+    optimizer.zero_grad(set_to_none=True)
+    running: list[dict[str, float | str]] = []
+    epoch = 0
+    while global_step < args.max_steps:
+        epoch += 1
+        for item in loader:
+            if global_step >= args.max_steps:
+                break
+            if global_step == args.warmup_blocks_steps:
+                set_blocks_trainable(model, True)
+
+            inputs, target_hidden, target_velocity = move_pair_to_device(
+                item, device=device, dtype=dtype
+            )
+            started = time.perf_counter()
+            with torch.autocast(device_type="cuda", dtype=dtype):
+                output = model(**inputs)
+                hidden_loss = F.mse_loss(
+                    output["pred_hidden"].float(), target_hidden.float()
+                )
+                velocity_loss = F.mse_loss(
+                    output["pred_velocity"].float(), target_velocity.float()
+                )
+                loss = (
+                    args.hidden_weight * hidden_loss
+                    + args.velocity_weight * velocity_loss
+                )
+                scaled_loss = loss / args.gradient_accumulation_steps
+            scaled_loss.backward()
+            micro_step += 1
+            running.append(
+                {
+                    "pair_id": item["pair_id"],
+                    "loss": float(loss.detach()),
+                    "hidden_mse": float(hidden_loss.detach()),
+                    "velocity_mse": float(velocity_loss.detach()),
+                    "micro_time_s": time.perf_counter() - started,
+                }
+            )
+            del output, loss, scaled_loss, hidden_loss, velocity_loss
+
+            if micro_step % args.gradient_accumulation_steps:
+                continue
+            grad_norm = torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
+            optimizer.step()
+            scheduler.step()
+            optimizer.zero_grad(set_to_none=True)
+            global_step += 1
+
+            if global_step % args.log_every == 0 or global_step == 1:
+                torch.cuda.synchronize()
+                count = len(running)
+                record = {
+                    "global_step": global_step,
+                    "epoch": epoch,
+                    "loss": sum(float(x["loss"]) for x in running) / count,
+                    "hidden_mse": sum(float(x["hidden_mse"]) for x in running) / count,
+                    "velocity_mse": sum(float(x["velocity_mse"]) for x in running) / count,
+                    "grad_norm": float(grad_norm),
+                    "lr_fusion": optimizer.param_groups[0]["lr"],
+                    "lr_blocks": optimizer.param_groups[1]["lr"],
+                    "peak_memory_gib": torch.cuda.max_memory_allocated() / 2**30,
+                    "avg_micro_time_s": sum(float(x["micro_time_s"]) for x in running) / count,
+                }
+                with log_path.open("a", encoding="utf-8") as handle:
+                    handle.write(json.dumps(record, sort_keys=True) + "\n")
+                print(json.dumps(record, sort_keys=True), flush=True)
+                running.clear()
+
+            should_save = global_step % args.save_every == 0 or global_step == args.max_steps
+            if should_save:
+                weights_path = output_dir / f"predictor_step_{global_step:05d}.safetensors"
+                save_predictor_weights(model, weights_path)
+                if args.save_optimizer_state:
+                    latest = {
+                        "model": trainable_state_dict(model),
+                        "optimizer": optimizer.state_dict(),
+                        "scheduler": scheduler.state_dict(),
+                        "global_step": global_step,
+                        "micro_step": micro_step,
+                        "torch_rng_state": torch.get_rng_state(),
+                        "cuda_rng_state": torch.cuda.get_rng_state_all(),
+                        "args": vars(args),
+                        "predictor_config": model.config_dict,
+                        "weights_path": str(weights_path),
+                    }
+                    save_training_state(output_dir / "training_latest.pt", latest)
+                prune_snapshots(output_dir, args.keep_snapshots)
+
+
+if __name__ == "__main__":
+    main()

train_predictor_disca.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Eight-GPU training entry point for the project-local Predictor-DisCa."""
+
+from __future__ import annotations
+
+import sys
+
+from train_predictor_v4 import main
+
+
+def _has_option(name: str) -> bool:
+    return any(argument == name or argument.startswith(f"{name}=") for argument in sys.argv[1:])
+
+
+if __name__ == "__main__":
+    defaults = (
+        ("--predictor_variant", "disca"),
+        (
+            "--output_dir",
+            (
+                "checkpoints/predictor_disca_blocks0-53_bf16_8gpu_"
+                "flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab"
+            ),
+        ),
+        ("--source_blocks", "0,53"),
+        ("--swanlab_project", "HY-WorldPlay-Predictor-DisCa"),
+        (
+            "--swanlab_experiment",
+            (
+                "predictor-disca-blocks0-53-bf16-8gpu-flr1e-4-blr1e-5-"
+                "schedsteps2000-swarmup100-bwarmup100"
+            ),
+        ),
+    )
+    injected: list[str] = []
+    for option, value in defaults:
+        if not _has_option(option):
+            injected.extend((option, value))
+    if not _has_option("--bucket_by_context") and not _has_option("--no-bucket_by_context"):
+        injected.append("--no-bucket_by_context")
+    sys.argv[1:1] = injected
+    main()

train_predictor_v2.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""Single-GPU training for AR-context HY-WorldPlay Predictor-v2."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import random
+import time
+from pathlib import Path
+
+import swanlab
+import torch
+import torch.nn.functional as F
+from torch.optim import AdamW
+from torch.optim.lr_scheduler import LambdaLR
+from torch.utils.data import DataLoader
+
+from hyvideo.commons.infer_state import initialize_infer_state
+from models import HYWorldPlayPredictorV2, HYWorldPlayPredictorV3, PredictorV2Config
+from predictor_training.checkpoint import (
+    save_predictor_weights,
+    save_training_state,
+    trainable_state_dict,
+)
+from predictor_training.dataset_v2 import (
+    PredictorV2PairDataset,
+    move_v2_pair_to_device,
+    predictor_v2_collate,
+)
+from predictor_training.dataset_v3 import (
+    PredictorV3PairDataset,
+    move_v3_pair_to_device,
+    predictor_v3_collate,
+)
+
+
+def parse_source_blocks(value: str) -> tuple[int, int]:
+    result = tuple(int(part.strip()) for part in value.split(",") if part.strip())
+    if result not in {(0, 53), (1, 52)}:
+        raise argparse.ArgumentTypeError("source_blocks must be 0,53 or 1,52")
+    return result
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", default="datasets/predictor_v2/train_eval_manifest.jsonl")
+    parser.add_argument("--predictor_version", choices=("v2", "v3"), default="v2")
+    parser.add_argument("--source_blocks", type=parse_source_blocks, required=True)
+    parser.add_argument(
+        "--teacher_checkpoint",
+        default="models-ms/HY-WorldPlay/ar_distilled_action_model/diffusion_pytorch_model.safetensors",
+    )
+    parser.add_argument("--output_dir", required=True)
+    parser.add_argument("--max_steps", type=int, default=2000)
+    parser.add_argument("--batch_size", type=int, default=1)
+    parser.add_argument("--gradient_accumulation_steps", type=int, default=4)
+    parser.add_argument("--warmup_blocks_steps", type=int, default=100)
+    parser.add_argument("--scheduler_warmup_steps", type=int, default=100)
+    parser.add_argument("--fusion_lr", type=float, default=1e-4)
+    parser.add_argument("--blocks_lr", type=float, default=1e-5)
+    parser.add_argument("--weight_decay", type=float, default=0.01)
+    parser.add_argument("--hidden_weight", type=float, default=0.1)
+    parser.add_argument("--velocity_weight", type=float, default=1.0)
+    parser.add_argument("--grad_clip", type=float, default=1.0)
+    parser.add_argument("--log_every", type=int, default=10)
+    parser.add_argument("--save_every", type=int, default=500)
+    parser.add_argument("--keep_snapshots", type=int, default=2)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--num_workers", type=int, default=0)
+    parser.add_argument("--max_records", type=int, default=None)
+    parser.add_argument("--gradient_checkpointing", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--save_optimizer_state", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--resume", default=None)
+    parser.add_argument("--swanlab_project", default="HY-WorldPlay-Predictor-v2")
+    parser.add_argument("--swanlab_workspace", default=None)
+    parser.add_argument("--swanlab_experiment", default=None)
+    parser.add_argument("--swanlab_mode", choices=("cloud", "offline", "local", "disabled"), default="cloud")
+    return parser.parse_args()
+
+
+def initialize_runtime_state() -> None:
+    class Args:
+        sage_blocks_range = "0-53"
+        use_sageattn = False
+        enable_torch_compile = False
+        use_fp8_gemm = False
+        quant_type = "fp8-per-block"
+        include_patterns = "double_blocks"
+        use_vae_parallel = False
+
+    initialize_infer_state(Args())
+
+
+def make_scheduler(optimizer: torch.optim.Optimizer, warmup: int, total: int) -> LambdaLR:
+    def factor(step: int) -> float:
+        if step < warmup:
+            return max(1e-8, float(step + 1) / max(1, warmup))
+        progress = min(1.0, float(step - warmup) / max(1, total - warmup))
+        return 0.5 * (1.0 + math.cos(math.pi * progress))
+
+    return LambdaLR(optimizer, factor)
+
+
+def set_ar_blocks_trainable(model: HYWorldPlayPredictorV2, enabled: bool) -> None:
+    for block in model.double_blocks:
+        for name, parameter in block.named_parameters():
+            parameter.requires_grad_(enabled and not name.startswith("txt_"))
+
+
+def prune_snapshots(output_dir: Path, keep: int) -> None:
+    snapshots = sorted(output_dir.glob("predictor_step_*.safetensors"))
+    for path in snapshots[:-keep] if keep > 0 else snapshots:
+        path.unlink()
+
+
+def init_swanlab(args: argparse.Namespace, config: dict):
+    if args.swanlab_mode == "cloud":
+        api_key = os.environ.get("SWANLAB_API_KEY")
+        swanlab.login(api_key=api_key, save=False) if api_key else swanlab.login()
+    fusion_lr = f"{args.fusion_lr:.0e}".replace("e-0", "e-").replace("e+0", "e+")
+    blocks_lr = f"{args.blocks_lr:.0e}".replace("e-0", "e-").replace("e+0", "e+")
+    experiment = args.swanlab_experiment or (
+        f"predictor-{args.predictor_version}-blocks"
+        + "-".join(str(value) for value in args.source_blocks)
+        + f"-flr{fusion_lr}-blr{blocks_lr}-schedsteps{args.max_steps}"
+        + f"-swarmup{args.scheduler_warmup_steps}"
+        + f"-bwarmup{args.warmup_blocks_steps}"
+    )
+    return swanlab.init(
+        project=args.swanlab_project,
+        workspace=args.swanlab_workspace,
+        experiment_name=experiment,
+        description=(
+            f"HY-WorldPlay {args.predictor_version} AR-context Predictor, "
+            "fresh exact 10-case targets"
+        ),
+        tags=[
+            f"predictor-{args.predictor_version}",
+            "ar-context-kv",
+            f"blocks-{args.source_blocks[0]}-{args.source_blocks[1]}",
+        ],
+        config=config,
+        logdir=str(Path(args.output_dir).resolve() / "swanlab"),
+        mode=args.swanlab_mode,
+    )
+
+
+def main() -> None:
+    args = parse_args()
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required")
+    random.seed(args.seed)
+    torch.manual_seed(args.seed)
+    torch.cuda.manual_seed_all(args.seed)
+    initialize_runtime_state()
+    device = torch.device("cuda:0")
+    dtype = torch.bfloat16
+    output_dir = Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    log_path = output_dir / "train_log.jsonl"
+
+    dataset_class = (
+        PredictorV3PairDataset if args.predictor_version == "v3" else PredictorV2PairDataset
+    )
+    collate_fn = (
+        predictor_v3_collate if args.predictor_version == "v3" else predictor_v2_collate
+    )
+    move_pair = (
+        move_v3_pair_to_device
+        if args.predictor_version == "v3"
+        else move_v2_pair_to_device
+    )
+    dataset = dataset_class(
+        args.manifest,
+        source_block_ids=args.source_blocks,
+        max_records=args.max_records,
+    )
+    generator = torch.Generator().manual_seed(args.seed)
+    loader = DataLoader(
+        dataset,
+        batch_size=args.batch_size,
+        shuffle=True,
+        num_workers=args.num_workers,
+        pin_memory=False,
+        collate_fn=collate_fn,
+        generator=generator,
+    )
+
+    model_class = (
+        HYWorldPlayPredictorV3 if args.predictor_version == "v3" else HYWorldPlayPredictorV2
+    )
+    model = model_class(PredictorV2Config(source_block_ids=args.source_blocks))
+    model.load_teacher_initialization(args.teacher_checkpoint)
+    model.to(device=device, dtype=dtype)
+    model.enable_gradient_checkpointing(args.gradient_checkpointing)
+    model.train()
+
+    fusion_parameters = list(model.img_fusion.parameters()) + list(model.residual_out.parameters())
+    block_parameters = [
+        parameter for parameter in model.double_blocks.parameters() if parameter.requires_grad
+    ]
+    intended_trainable_parameters = sum(
+        parameter.numel() for parameter in fusion_parameters + block_parameters
+    )
+    intended_parameter_breakdown = model.trainable_parameter_breakdown()
+    optimizer = AdamW(
+        [
+            {"params": fusion_parameters, "lr": args.fusion_lr},
+            {"params": block_parameters, "lr": args.blocks_lr},
+        ],
+        betas=(0.9, 0.95),
+        weight_decay=args.weight_decay,
+    )
+    scheduler = make_scheduler(optimizer, args.scheduler_warmup_steps, args.max_steps)
+    global_step = 0
+    micro_step = 0
+    set_ar_blocks_trainable(model, args.warmup_blocks_steps <= 0)
+
+    if args.resume:
+        state = torch.load(args.resume, map_location="cpu", weights_only=False)
+        if tuple(state["predictor_config"]["source_block_ids"]) != args.source_blocks:
+            raise ValueError("Resume checkpoint source blocks do not match")
+        model.load_state_dict(state["model"], strict=False)
+        optimizer.load_state_dict(state["optimizer"])
+        scheduler.load_state_dict(state["scheduler"])
+        global_step = int(state["global_step"])
+        micro_step = int(state.get("micro_step", global_step * args.gradient_accumulation_steps))
+        if "torch_rng_state" in state:
+            torch.set_rng_state(state["torch_rng_state"])
+        if "cuda_rng_state" in state:
+            torch.cuda.set_rng_state_all(state["cuda_rng_state"])
+        set_ar_blocks_trainable(model, global_step >= args.warmup_blocks_steps)
+
+    run_config = {
+        **vars(args),
+        "source_blocks": list(args.source_blocks),
+        "manifest": str(Path(args.manifest).resolve()),
+        "teacher_checkpoint": str(Path(args.teacher_checkpoint).resolve()),
+        "dataset_pairs": len(dataset),
+        "effective_batch_size": args.batch_size * args.gradient_accumulation_steps,
+        "trainable_parameters": intended_trainable_parameters,
+        "parameter_breakdown": intended_parameter_breakdown,
+        "dtype": "bfloat16",
+        "predictor_version": args.predictor_version,
+        "gpu": torch.cuda.get_device_name(device),
+    }
+    run = init_swanlab(args, run_config)
+    print(
+        json.dumps(
+            {
+                "dataset_pairs": len(dataset),
+                "source_blocks": args.source_blocks,
+                "trainable_parameters": intended_trainable_parameters,
+                "breakdown": intended_parameter_breakdown,
+                "start_step": global_step,
+                "swanlab_run_id": getattr(run, "id", None),
+            },
+            indent=2,
+        ),
+        flush=True,
+    )
+
+    optimizer.zero_grad(set_to_none=True)
+    running: list[dict[str, float | str]] = []
+    epoch = 0
+    try:
+        while global_step < args.max_steps:
+            epoch += 1
+            for item in loader:
+                if global_step >= args.max_steps:
+                    break
+                if global_step == args.warmup_blocks_steps:
+                    set_ar_blocks_trainable(model, True)
+
+                inputs, target_hidden, target_velocity = move_pair(
+                    item, device=device, dtype=dtype
+                )
+                started = time.perf_counter()
+                with torch.autocast(device_type="cuda", dtype=dtype):
+                    output = model(**inputs)
+                    hidden_loss = F.mse_loss(
+                        output["pred_hidden"].float(), target_hidden.float()
+                    )
+                    velocity_loss = F.mse_loss(
+                        output["pred_velocity"].float(), target_velocity.float()
+                    )
+                    loss = args.hidden_weight * hidden_loss + args.velocity_weight * velocity_loss
+                    scaled_loss = loss / args.gradient_accumulation_steps
+                scaled_loss.backward()
+                micro_step += 1
+                running.append(
+                    {
+                        "pair_id": ",".join(item["pair_id"]),
+                        "loss": float(loss.detach()),
+                        "hidden_mse": float(hidden_loss.detach()),
+                        "velocity_mse": float(velocity_loss.detach()),
+                        "micro_time_s": time.perf_counter() - started,
+                        "context_frames": sum(item["context_frames"])
+                        / len(item["context_frames"]),
+                    }
+                )
+                del (
+                    output,
+                    loss,
+                    scaled_loss,
+                    hidden_loss,
+                    velocity_loss,
+                    inputs,
+                    target_hidden,
+                    target_velocity,
+                    item,
+                )
+
+                if micro_step % args.gradient_accumulation_steps:
+                    continue
+                grad_norm = torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
+                optimizer.step()
+                scheduler.step()
+                optimizer.zero_grad(set_to_none=True)
+                global_step += 1
+
+                if global_step % args.log_every == 0 or global_step == 1:
+                    torch.cuda.synchronize()
+                    count = len(running)
+                    record = {
+                        "global_step": global_step,
+                        "epoch": epoch,
+                        "loss": sum(float(x["loss"]) for x in running) / count,
+                        "hidden_mse": sum(float(x["hidden_mse"]) for x in running) / count,
+                        "velocity_mse": sum(float(x["velocity_mse"]) for x in running) / count,
+                        "grad_norm": float(grad_norm),
+                        "lr_fusion": optimizer.param_groups[0]["lr"],
+                        "lr_blocks": optimizer.param_groups[1]["lr"],
+                        "peak_memory_gib": torch.cuda.max_memory_allocated() / 2**30,
+                        "avg_micro_time_s": sum(float(x["micro_time_s"]) for x in running) / count,
+                        "avg_context_frames": sum(float(x["context_frames"]) for x in running) / count,
+                    }
+                    with log_path.open("a", encoding="utf-8") as handle:
+                        handle.write(json.dumps(record, sort_keys=True) + "\n")
+                    swanlab.log(record, step=global_step)
+                    print(json.dumps(record, sort_keys=True), flush=True)
+                    running.clear()
+
+                should_save = global_step % args.save_every == 0 or global_step == args.max_steps
+                if should_save:
+                    weights_path = output_dir / f"predictor_step_{global_step:05d}.safetensors"
+                    save_predictor_weights(model, weights_path)
+                    if args.save_optimizer_state:
+                        latest = {
+                            "model": trainable_state_dict(model),
+                            "optimizer": optimizer.state_dict(),
+                            "scheduler": scheduler.state_dict(),
+                            "global_step": global_step,
+                            "micro_step": micro_step,
+                            "torch_rng_state": torch.get_rng_state(),
+                            "cuda_rng_state": torch.cuda.get_rng_state_all(),
+                            "args": vars(args),
+                            "predictor_config": model.config_dict,
+                            "weights_path": str(weights_path),
+                        }
+                        save_training_state(output_dir / "training_latest.pt", latest)
+                    prune_snapshots(output_dir, args.keep_snapshots)
+    except BaseException as error:
+        swanlab.finish(error=error)
+        raise
+    else:
+        swanlab.finish()
+
+
+if __name__ == "__main__":
+    main()

train_predictor_v3.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Single-GPU training entry point for previous-chunk Predictor-v3."""
+
+from __future__ import annotations
+
+import sys
+
+from train_predictor_v2 import main
+
+
+if __name__ == "__main__":
+    if "--predictor_version" not in sys.argv:
+        sys.argv[1:1] = ["--predictor_version", "v3"]
+    main()

train_predictor_v4.py

@@ -0,0 +1,1030 @@
+#!/usr/bin/env python3
+"""Eight-GPU DDP training engine for Predictor-v4 and Predictor-DisCa."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import random
+import time
+from pathlib import Path
+
+import torch
+import torch.distributed as dist
+import torch.nn.functional as F
+import swanlab
+from torch.nn.parallel import DistributedDataParallel as DDP
+from torch.optim import AdamW
+from torch.optim.lr_scheduler import LambdaLR
+from torch.utils.data import DataLoader
+from torch.utils.data.distributed import DistributedSampler
+
+from hyvideo.commons.infer_state import initialize_infer_state
+from hyvideo.commons.parallel_states import initialize_parallel_state
+from models import HYWorldPlayPredictorDisCa, HYWorldPlayPredictorV4, PredictorV2Config
+from predictor_training.bucket_sampler import DistributedContextBucketBatchSampler
+from predictor_training.checkpoint import (
+    load_concat_fusion_initialization,
+    load_concat_residual_gate_initialization,
+    save_predictor_weights,
+    save_training_state,
+    trainable_state_dict,
+)
+from predictor_training.dataset_prefeature import (
+    PredictorPrefeaturePairDataset,
+    move_prefeature_pair_to_device,
+    predictor_prefeature_collate,
+)
+from predictor_training.dataset_disca import (
+    PredictorDisCaPairDataset,
+    move_disca_pair_to_device,
+    predictor_disca_collate,
+)
+
+
+DEFAULT_MANIFEST = (
+    "/mnt/local_nvme/zoubin/cz/hyworldplay_predictor_prefeature_v4/"
+    "train_eval_manifest.jsonl"
+)
+DEFAULT_TEACHER = (
+    "/mnt/s3files/s3-us-west2-default/zoubin/cz/checkpoints/hy_worldplay/"
+    "huggingface/hub/models--tencent--HY-WorldPlay/snapshots/"
+    "f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/"
+    "diffusion_pytorch_model.safetensors"
+)
+DEFAULT_OUTPUT = (
+    "/mnt/s3files/s3-us-west2-default/zoubin/cz/projects/"
+    "HY-WorldPlay-DEV-Predictor/checkpoints/"
+    "predictor_v4_prefeature_blocks0-53_bf16_8gpu_flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab"
+)
+
+
+def parse_source_blocks(value: str) -> tuple[int, int]:
+    result = tuple(int(part.strip()) for part in value.split(",") if part.strip())
+    if result not in {(0, 53), (1, 52)}:
+        raise argparse.ArgumentTypeError("source_blocks must be 0,53 or 1,52")
+    return result
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", default=DEFAULT_MANIFEST)
+    parser.add_argument("--teacher_checkpoint", default=DEFAULT_TEACHER)
+    parser.add_argument("--output_dir", default=DEFAULT_OUTPUT)
+    parser.add_argument("--source_blocks", type=parse_source_blocks, default=(0, 53))
+    parser.add_argument(
+        "--predictor_variant", choices=("v4", "disca"), default="v4",
+        help="Use v4 Context/previous-chunk inputs or the Predictor-DisCa ablation",
+    )
+    parser.add_argument(
+        "--previous_condition_mode",
+        choices=("none", "same_step", "previous_step", "both", "both_delta_gated"),
+        default="same_step",
+        help="Explicit previous-chunk hidden condition used by Predictor-v4",
+    )
+    parser.add_argument(
+        "--predictor_fusion_type",
+        choices=(
+            "concat",
+            "projection_add",
+            "token_gate_prev",
+            "concat_residual_gate_prev",
+        ),
+        default="concat",
+        help="Image-token fusion architecture; non-concat modes require same_step",
+    )
+    parser.add_argument("--gate_hidden_dim", type=int, default=256)
+    parser.add_argument("--gate_initial_probability", type=float, default=0.8)
+    parser.add_argument("--predictor_arch", choices=("baseline", "atc"), default="baseline")
+    parser.add_argument(
+        "--atc_variant",
+        choices=("full", "anchor_only", "raw_prev", "no_gate", "no_distance"),
+        default="full",
+    )
+    parser.add_argument("--atc_mlp_hidden_dim", type=int, default=4096)
+    parser.add_argument("--atc_gate_hidden_dim", type=int, default=512)
+    parser.add_argument("--atc_gate_initial_probability", type=float, default=0.3)
+    parser.add_argument(
+        "--atc_transport_heads", type=int, default=None,
+        help="Transport attention heads; default = Teacher heads so head_dim matches the Teacher RoPE.",
+    )
+    parser.add_argument(
+        "--atc_transport_mode", choices=("global", "local"), default="global",
+        help="global: Causal-Forcing RoPE'd global cross-chunk attention; local: legacy 3x3 window.",
+    )
+    parser.add_argument(
+        "--atc_previous_scope", choices=("chunk", "last_frame"), default="chunk",
+        help="Keys of the global transport: whole previous chunk or only its last frame.",
+    )
+    parser.add_argument("--atc_transport_window", type=int, default=3)
+    parser.add_argument("--atc_transport_query_chunk_size", type=int, default=128)
+    parser.add_argument("--atc_transport_initial_scale", type=float, default=0.1)
+    parser.add_argument("--max_steps", type=int, default=2000)
+    parser.add_argument("--batch_size", type=int, default=16, help="Per-rank batch size")
+    parser.add_argument("--gradient_accumulation_steps", type=int, default=1)
+    parser.add_argument("--block_warmup_steps", type=int, default=100)
+    parser.add_argument(
+        "--block_warmup_mode",
+        choices=("delayed", "linear"),
+        default="delayed",
+        help=(
+            "Use the original Stage-1 delayed block start or linearly warm the "
+            "block group from the beginning"
+        ),
+    )
+    parser.add_argument("--scheduler_warmup_steps", type=int, default=100)
+    parser.add_argument("--fusion_lr", type=float, default=1e-4)
+    parser.add_argument("--blocks_lr", type=float, default=1e-5)
+    parser.add_argument("--weight_decay", type=float, default=0.01)
+    parser.add_argument("--hidden_weight", type=float, default=0.1)
+    parser.add_argument("--velocity_weight", type=float, default=1.0)
+    parser.add_argument("--grad_clip", type=float, default=1.0)
+    parser.add_argument("--log_every", type=int, default=10)
+    parser.add_argument("--save_every", type=int, default=100)
+    parser.add_argument("--keep_snapshots", type=int, default=20)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--num_workers", type=int, default=0)
+    parser.add_argument("--max_records", type=int, default=None)
+    parser.add_argument(
+        "--bucket_by_context", action=argparse.BooleanOptionalAction, default=True
+    )
+    parser.add_argument(
+        "--gradient_checkpointing", action=argparse.BooleanOptionalAction, default=True
+    )
+    parser.add_argument(
+        "--fp32_trainable_params",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=(
+            "Keep requires_grad=True Predictor parameters and AdamW moments in "
+            "FP32 while frozen parameters and forward activations remain BF16"
+        ),
+    )
+    parser.add_argument(
+        "--train_delta_only",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=(
+            "Freeze the inherited same-step Predictor and optimize only the "
+            "both_delta_gated residual branch."
+        ),
+    )
+    parser.add_argument(
+        "--train_fusion_residual_only",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=(
+            "Freeze the inherited concat fusion and Predictor blocks, and train "
+            "only the zero-initialized concat_residual_gate_prev branch."
+        ),
+    )
+    parser.add_argument(
+        "--save_optimizer_state", action=argparse.BooleanOptionalAction, default=True
+    )
+    parser.add_argument(
+        "--init_training_state",
+        default=None,
+        help=(
+            "Load only the FP32 Predictor model state from training_latest.pt "
+            "while starting a fresh optimizer, scheduler, and step counter"
+        ),
+    )
+    parser.add_argument("--resume", default=None)
+    parser.add_argument("--swanlab_project", default="HY-WorldPlay-Predictor-v4")
+    parser.add_argument("--swanlab_workspace", default=None)
+    parser.add_argument(
+        "--swanlab_experiment",
+        default=(
+            "predictor-v4-prefeature-blocks0-53-bf16-8gpu-"
+            "flr1e-4-blr1e-5-schedsteps2000-swarmup100-bwarmup100"
+        ),
+    )
+    parser.add_argument(
+        "--swanlab_mode",
+        choices=("cloud", "offline", "local", "disabled"),
+        default="cloud",
+    )
+    return parser.parse_args()
+
+
+def initialize_runtime_state() -> None:
+    class Args:
+        sage_blocks_range = "0-53"
+        use_sageattn = False
+        enable_torch_compile = False
+        use_fp8_gemm = False
+        quant_type = "fp8-per-block"
+        include_patterns = "double_blocks"
+        use_vae_parallel = False
+
+    initialize_infer_state(Args())
+
+
+def cosine_factor(step: int, warmup: int, total: int) -> float:
+    if step < warmup:
+        return max(1e-8, float(step + 1) / max(1, warmup))
+    progress = min(1.0, float(step - warmup) / max(1, total - warmup))
+    return 0.5 * (1.0 + math.cos(math.pi * progress))
+
+
+def make_scheduler(optimizer: torch.optim.Optimizer, args: argparse.Namespace) -> LambdaLR:
+    def block_factor(step: int) -> float:
+        if args.block_warmup_mode == "linear":
+            return cosine_factor(step, args.block_warmup_steps, args.max_steps)
+        return (
+            0.0
+            if step < args.block_warmup_steps
+            else cosine_factor(step, args.scheduler_warmup_steps, args.max_steps)
+        )
+
+    return LambdaLR(
+        optimizer,
+        [
+            lambda step: cosine_factor(step, args.scheduler_warmup_steps, args.max_steps),
+            block_factor,
+        ],
+    )
+
+
+def prune_snapshots(output_dir: Path, keep: int) -> None:
+    snapshots = sorted(output_dir.glob("predictor_step_*.safetensors"))
+    for path in snapshots[:-keep] if keep > 0 else snapshots:
+        path.unlink()
+
+
+def distributed_mean(values: torch.Tensor) -> torch.Tensor:
+    dist.all_reduce(values, op=dist.ReduceOp.SUM)
+    values /= dist.get_world_size()
+    return values
+
+
+def configure_model_precision(
+    model: torch.nn.Module,
+    *,
+    device: torch.device,
+    activation_dtype: torch.dtype,
+    fp32_trainable_params: bool,
+) -> None:
+    """Place frozen state in BF16 and optionally retain FP32 master parameters."""
+    model.to(device=device, dtype=activation_dtype)
+    if fp32_trainable_params:
+        with torch.no_grad():
+            for parameter in model.parameters():
+                if parameter.requires_grad:
+                    parameter.data = parameter.data.to(dtype=torch.float32)
+
+
+def validate_optimizer_precision(
+    optimizer: torch.optim.Optimizer,
+    *,
+    fp32_trainable_params: bool,
+    require_state: bool,
+) -> None:
+    expected = torch.float32 if fp32_trainable_params else torch.bfloat16
+    for group in optimizer.param_groups:
+        for parameter in group["params"]:
+            if parameter.dtype != expected:
+                raise RuntimeError(
+                    f"Optimizer parameter dtype {parameter.dtype} != expected {expected}"
+                )
+            state = optimizer.state.get(parameter, {})
+            for name in ("exp_avg", "exp_avg_sq"):
+                value = state.get(name)
+                if value is None:
+                    if require_state:
+                        raise RuntimeError(f"Optimizer state {name} has not been initialized")
+                    continue
+                if value.dtype != expected:
+                    raise RuntimeError(
+                        f"Optimizer state {name} dtype {value.dtype} != expected {expected}"
+                    )
+
+
+def configure_delta_only_trainability(model: torch.nn.Module) -> None:
+    if getattr(model, "previous_condition_mode", None) != "both_delta_gated":
+        raise ValueError("--train_delta_only requires both_delta_gated mode")
+    model.requires_grad_(False)
+    model.img_fusion.previous_step_norm.requires_grad_(True)
+    model.img_fusion.delta_mlp.requires_grad_(True)
+    model.img_fusion.delta_gate.requires_grad_(True)
+
+
+def configure_fusion_residual_only_trainability(model: torch.nn.Module) -> None:
+    fusion_type = getattr(
+        getattr(model, "predictor_config", None), "predictor_fusion_type", None
+    )
+    if fusion_type != "concat_residual_gate_prev":
+        raise ValueError(
+            "--train_fusion_residual_only requires "
+            "concat_residual_gate_prev fusion"
+        )
+    model.requires_grad_(False)
+    model.img_fusion.gate_p.requires_grad_(True)
+    model.img_fusion.residual_mlp.requires_grad_(True)
+
+
+def load_initial_training_state(
+    model: torch.nn.Module,
+    path: Path,
+    *,
+    source_blocks: tuple[int, int],
+    predictor_variant: str,
+    previous_condition_mode: str,
+    predictor_fusion_type: str,
+    fp32_trainable_params: bool,
+) -> None:
+    """Load only a prior FP32 Predictor model state for a fresh training branch."""
+    state = torch.load(path, map_location="cpu", weights_only=False)
+    if tuple(state["predictor_config"]["source_block_ids"]) != source_blocks:
+        raise ValueError("Initialization checkpoint source blocks do not match")
+    saved_variant = state.get("args", {}).get("predictor_variant", "v4")
+    if saved_variant != predictor_variant:
+        raise ValueError("Initialization checkpoint predictor variant does not match")
+    saved_mode = state.get("args", {}).get(
+        "previous_condition_mode",
+        state.get("predictor_config", {}).get("previous_condition_mode", "same_step"),
+    )
+    delta_from_same_step = (
+        saved_mode == "same_step" and previous_condition_mode == "both_delta_gated"
+    )
+    if saved_mode != previous_condition_mode and not delta_from_same_step:
+        raise ValueError(
+            "Initialization checkpoint previous-condition mode does not match: "
+            f"saved={saved_mode}, requested={previous_condition_mode}"
+        )
+    saved_fp32_master = bool(
+        state.get("args", {}).get("fp32_trainable_params", False)
+    )
+    if not saved_fp32_master or not fp32_trainable_params:
+        raise ValueError(
+            "Model-only initialization requires both the checkpoint and current "
+            "run to use FP32 trainable parameters"
+        )
+    saved_fusion_type = state.get("predictor_config", {}).get(
+        "predictor_fusion_type",
+        state.get("args", {}).get("predictor_fusion_type", "concat"),
+    )
+    concat_conversion = (
+        saved_fusion_type == "concat"
+        and predictor_fusion_type in {"projection_add", "token_gate_prev"}
+        and saved_mode == previous_condition_mode == "same_step"
+    )
+    concat_residual_initialization = (
+        saved_fusion_type == "concat"
+        and predictor_fusion_type == "concat_residual_gate_prev"
+        and saved_mode == previous_condition_mode == "same_step"
+    )
+    if (
+        saved_fusion_type != predictor_fusion_type
+        and not concat_conversion
+        and not concat_residual_initialization
+    ):
+        raise ValueError(
+            "Initialization checkpoint fusion type does not match: "
+            f"saved={saved_fusion_type}, requested={predictor_fusion_type}"
+        )
+    if concat_conversion:
+        conversion = load_concat_fusion_initialization(model, state["model"])
+        print(
+            json.dumps(
+                {
+                    "fusion_initialization": "concat_conversion",
+                    "discarded_concat_key_count": len(
+                        conversion["discarded_concat_keys"]
+                    ),
+                    "fresh_fusion_key_count": len(conversion["fresh_fusion_keys"]),
+                },
+                sort_keys=True,
+            ),
+            flush=True,
+        )
+        return
+    if concat_residual_initialization:
+        conversion = load_concat_residual_gate_initialization(
+            model, state["model"]
+        )
+        print(
+            json.dumps(
+                {
+                    "fusion_initialization": "concat_residual_gate",
+                    "fresh_residual_key_count": len(
+                        conversion["fresh_residual_keys"]
+                    ),
+                },
+                sort_keys=True,
+            ),
+            flush=True,
+        )
+        return
+
+    result = model.load_state_dict(state["model"], strict=False)
+    trainable_names = {
+        name for name, parameter in model.named_parameters() if parameter.requires_grad
+    }
+    allowed_missing = set()
+    if delta_from_same_step:
+        allowed_missing = {
+            name
+            for name in trainable_names
+            if name.startswith("img_fusion.previous_step_norm.")
+            or name.startswith("img_fusion.delta_mlp.")
+            or name == "img_fusion.delta_gate"
+        }
+        with torch.no_grad():
+            model.img_fusion.previous_step_norm.load_state_dict(
+                model.img_fusion.previous_norm.state_dict(), strict=True
+            )
+    missing_trainable = sorted(
+        trainable_names.intersection(result.missing_keys) - allowed_missing
+    )
+    if result.unexpected_keys or missing_trainable:
+        raise RuntimeError(
+            "Initialization training-state mismatch; "
+            f"unexpected={result.unexpected_keys}, "
+            f"missing_trainable={missing_trainable}"
+        )
+
+
+def main() -> None:
+    args = parse_args()
+    if args.predictor_arch == "atc" and (
+        args.predictor_variant != "v4" or args.previous_condition_mode != "same_step"
+    ):
+        raise ValueError("ATC requires predictor_variant=v4 and previous_condition_mode=same_step")
+    if args.predictor_variant != "v4" and args.previous_condition_mode != "same_step":
+        raise ValueError("previous_condition_mode ablations require predictor_variant=v4")
+    if args.predictor_variant != "v4" and args.predictor_fusion_type != "concat":
+        raise ValueError("Non-concat fusion types require predictor_variant=v4")
+    if (
+        args.predictor_fusion_type != "concat"
+        and args.previous_condition_mode != "same_step"
+    ):
+        raise ValueError("Non-concat fusion types require previous_condition_mode=same_step")
+    if args.resume and args.init_training_state:
+        raise ValueError("--resume and --init_training_state are mutually exclusive")
+    if args.train_delta_only and args.train_fusion_residual_only:
+        raise ValueError(
+            "--train_delta_only and --train_fusion_residual_only are mutually exclusive"
+        )
+    if args.train_fusion_residual_only and not (
+        args.init_training_state or args.resume
+    ):
+        raise ValueError(
+            "--train_fusion_residual_only requires --init_training_state or --resume"
+        )
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required")
+    if not {"RANK", "WORLD_SIZE", "LOCAL_RANK"}.issubset(os.environ):
+        raise RuntimeError("Launch Predictor-v4 training with torchrun")
+    rank = int(os.environ["RANK"])
+    world_size = int(os.environ["WORLD_SIZE"])
+    local_rank = int(os.environ["LOCAL_RANK"])
+    torch.cuda.set_device(local_rank)
+    device = torch.device("cuda", local_rank)
+    dist.init_process_group(backend="nccl", device_id=device)
+    initialize_parallel_state(sp=1)
+    initialize_runtime_state()
+    dtype = torch.bfloat16
+
+    seed = args.seed + rank
+    random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+    output_dir = Path(args.output_dir).resolve()
+    if rank == 0:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    dist.barrier()
+    log_path = output_dir / "train_log.jsonl"
+
+    if args.predictor_variant == "disca":
+        dataset = PredictorDisCaPairDataset(
+            args.manifest,
+            source_block_ids=args.source_blocks,
+            max_records=args.max_records,
+        )
+        collate_fn = predictor_disca_collate
+        move_batch = move_disca_pair_to_device
+    else:
+        dataset = PredictorPrefeaturePairDataset(
+            args.manifest,
+            source_block_ids=args.source_blocks,
+            require_previous_chunk=True,
+            previous_condition_mode=args.previous_condition_mode,
+            max_records=args.max_records,
+        )
+        collate_fn = predictor_prefeature_collate
+        move_batch = move_prefeature_pair_to_device
+    bucket_sampler = None
+    distributed_sampler = None
+    if args.bucket_by_context:
+        bucket_sampler = DistributedContextBucketBatchSampler(
+            dataset,
+            batch_size=args.batch_size,
+            rank=rank,
+            world_size=world_size,
+            seed=args.seed,
+            drop_last=True,
+        )
+        loader = DataLoader(
+            dataset,
+            batch_sampler=bucket_sampler,
+            num_workers=args.num_workers,
+            pin_memory=False,
+            collate_fn=collate_fn,
+        )
+    else:
+        distributed_sampler = DistributedSampler(
+            dataset,
+            num_replicas=world_size,
+            rank=rank,
+            shuffle=True,
+            seed=args.seed,
+            drop_last=True,
+        )
+        loader = DataLoader(
+            dataset,
+            batch_size=args.batch_size,
+            sampler=distributed_sampler,
+            drop_last=True,
+            num_workers=args.num_workers,
+            pin_memory=False,
+            collate_fn=collate_fn,
+        )
+    if len(loader) == 0:
+        raise ValueError("Training loader has zero batches")
+
+    model_class = (
+        HYWorldPlayPredictorDisCa
+        if args.predictor_variant == "disca"
+        else HYWorldPlayPredictorV4
+    )
+    model = model_class(
+        PredictorV2Config(
+            source_block_ids=args.source_blocks,
+            previous_condition_mode=args.previous_condition_mode,
+            predictor_fusion_type=args.predictor_fusion_type,
+            gate_hidden_dim=args.gate_hidden_dim,
+            gate_initial_probability=args.gate_initial_probability,
+            predictor_arch=args.predictor_arch,
+            atc_variant=args.atc_variant,
+            atc_mlp_hidden_dim=args.atc_mlp_hidden_dim,
+            atc_gate_hidden_dim=args.atc_gate_hidden_dim,
+            atc_gate_initial_probability=args.atc_gate_initial_probability,
+            atc_transport_heads=args.atc_transport_heads,
+            atc_transport_window=args.atc_transport_window,
+            atc_transport_query_chunk_size=args.atc_transport_query_chunk_size,
+            atc_transport_initial_scale=args.atc_transport_initial_scale,
+            atc_transport_mode=args.atc_transport_mode,
+            atc_previous_scope=args.atc_previous_scope,
+        )
+    )
+    model.load_teacher_initialization(args.teacher_checkpoint)
+    if args.train_delta_only:
+        configure_delta_only_trainability(model)
+    if args.train_fusion_residual_only:
+        configure_fusion_residual_only_trainability(model)
+    configure_model_precision(
+        model,
+        device=device,
+        activation_dtype=dtype,
+        fp32_trainable_params=args.fp32_trainable_params,
+    )
+    if args.init_training_state:
+        initialization_path = Path(args.init_training_state).resolve()
+        if not initialization_path.is_file():
+            raise FileNotFoundError(initialization_path)
+        load_initial_training_state(
+            model,
+            initialization_path,
+            source_blocks=args.source_blocks,
+            predictor_variant=args.predictor_variant,
+            previous_condition_mode=args.previous_condition_mode,
+            predictor_fusion_type=args.predictor_fusion_type,
+            fp32_trainable_params=args.fp32_trainable_params,
+        )
+    model.enable_gradient_checkpointing(args.gradient_checkpointing)
+    model.train()
+    if args.predictor_variant == "v4" and any(
+        parameter.requires_grad for parameter in model.context_projector.parameters()
+    ):
+        raise RuntimeError("Frozen Context projector unexpectedly has trainable parameters")
+
+    fusion_parameters = [
+        parameter
+        for parameter in (
+            list(model.img_fusion.parameters())
+            + list(model.residual_out.parameters())
+        )
+        if parameter.requires_grad
+    ]
+    block_parameters = [
+        parameter
+        for parameter in model.double_blocks.parameters()
+        if parameter.requires_grad
+    ]
+    optimizer = AdamW(
+        [
+            {"params": fusion_parameters, "lr": args.fusion_lr},
+            {"params": block_parameters, "lr": args.blocks_lr},
+        ],
+        betas=(0.9, 0.95),
+        weight_decay=args.weight_decay,
+    )
+    validate_optimizer_precision(
+        optimizer,
+        fp32_trainable_params=args.fp32_trainable_params,
+        require_state=False,
+    )
+    scheduler = make_scheduler(optimizer, args)
+    global_step = 0
+    micro_step = 0
+    epoch = 0
+
+    if args.resume:
+        state = torch.load(args.resume, map_location="cpu", weights_only=False)
+        if tuple(state["predictor_config"]["source_block_ids"]) != args.source_blocks:
+            raise ValueError("Resume checkpoint source blocks do not match")
+        saved_variant = state.get("args", {}).get("predictor_variant", "v4")
+        if saved_variant != args.predictor_variant:
+            raise ValueError("Resume checkpoint predictor variant does not match")
+        saved_arch = state.get("predictor_config", {}).get(
+            "predictor_arch", state.get("args", {}).get("predictor_arch", "baseline")
+        )
+        saved_atc_variant = state.get("predictor_config", {}).get(
+            "atc_variant", state.get("args", {}).get("atc_variant", "full")
+        )
+        if saved_arch != args.predictor_arch:
+            raise ValueError(
+                f"Resume predictor architecture mismatch: saved={saved_arch}, "
+                f"requested={args.predictor_arch}"
+            )
+        if saved_arch == "atc" and saved_atc_variant != args.atc_variant:
+            raise ValueError(
+                f"Resume ATC variant mismatch: saved={saved_atc_variant}, "
+                f"requested={args.atc_variant}"
+            )
+        if saved_arch == "atc":
+            saved_cfg = state.get("predictor_config", {})
+            # Checkpoints written before the transport switch are local-window ATC.
+            saved_transport = saved_cfg.get("atc_transport_mode", "local")
+            saved_scope = saved_cfg.get("atc_previous_scope", "chunk")
+            if (saved_transport, saved_scope) != (args.atc_transport_mode, args.atc_previous_scope):
+                raise ValueError(
+                    f"Resume ATC transport mismatch: saved={saved_transport}/{saved_scope}, "
+                    f"requested={args.atc_transport_mode}/{args.atc_previous_scope}"
+                )
+        saved_mode = state.get("args", {}).get(
+            "previous_condition_mode",
+            state.get("predictor_config", {}).get(
+                "previous_condition_mode", "same_step"
+            ),
+        )
+        if saved_mode != args.previous_condition_mode:
+            raise ValueError(
+                "Resume checkpoint previous-condition mode does not match: "
+                f"saved={saved_mode}, requested={args.previous_condition_mode}"
+            )
+        saved_fusion_type = state.get("predictor_config", {}).get(
+            "predictor_fusion_type",
+            state.get("args", {}).get("predictor_fusion_type", "concat"),
+        )
+        if saved_fusion_type != args.predictor_fusion_type:
+            raise ValueError(
+                "Resume checkpoint fusion type does not match: "
+                f"saved={saved_fusion_type}, requested={args.predictor_fusion_type}"
+            )
+        saved_fp32_master = bool(
+            state.get("args", {}).get("fp32_trainable_params", False)
+        )
+        if saved_fp32_master != args.fp32_trainable_params:
+            raise ValueError("Resume checkpoint FP32-master setting does not match")
+        result = model.load_state_dict(state["model"], strict=False)
+        missing_trainable = [
+            key
+            for key in result.missing_keys
+            if key.startswith(("img_fusion.", "double_blocks.", "residual_out."))
+        ]
+        if result.unexpected_keys or missing_trainable:
+            raise RuntimeError(
+                "Resume model mismatch; "
+                f"unexpected={result.unexpected_keys}, missing={missing_trainable}"
+            )
+        optimizer.load_state_dict(state["optimizer"])
+        validate_optimizer_precision(
+            optimizer,
+            fp32_trainable_params=args.fp32_trainable_params,
+            require_state=True,
+        )
+        scheduler.load_state_dict(state["scheduler"])
+        global_step = int(state["global_step"])
+        micro_step = int(state.get("micro_step", global_step))
+        epoch = int(state.get("epoch", 0))
+
+    ddp = DDP(
+        model,
+        device_ids=[local_rank],
+        output_device=local_rank,
+        broadcast_buffers=False,
+        gradient_as_bucket_view=True,
+        find_unused_parameters=False,
+    )
+    trainable_parameters = sum(
+        parameter.numel() for parameter in model.parameters() if parameter.requires_grad
+    )
+    frozen_projector_parameters = sum(
+        parameter.numel() for parameter in getattr(model, "context_projector", ()).parameters()
+    ) if hasattr(model, "context_projector") else 0
+    run_config = {
+        **vars(args),
+        "manifest": str(Path(args.manifest).resolve()),
+        "teacher_checkpoint": str(Path(args.teacher_checkpoint).resolve()),
+        "output_dir": str(output_dir),
+        "source_blocks": list(args.source_blocks),
+        "predictor_version": (
+            "predictor_disca" if args.predictor_variant == "disca" else "v4_prefeature"
+        ),
+        "schema_version": (
+            "predictor_disca_text_kv_v1"
+            if args.predictor_variant == "disca"
+            else "predictor_context_prefeature_bf16_v1"
+        ),
+        "supervision_pairs": [[0, 1], [1, 2], [2, 3]],
+        "previous_condition_mode": args.previous_condition_mode,
+        "previous_condition_source": "offline_full_teacher_hidden",
+        "records": len(dataset.records),
+        "dataset_pairs": len(dataset),
+        "steps_per_epoch_per_rank": len(loader),
+        "world_size": world_size,
+        "per_rank_batch_size": args.batch_size,
+        "global_batch_size": (
+            args.batch_size * world_size * args.gradient_accumulation_steps
+        ),
+        "trainable_parameters": trainable_parameters,
+        "frozen_projector_parameters": frozen_projector_parameters,
+        "dtype": "bfloat16",
+        "activation_dtype": "bfloat16",
+        "trainable_parameter_dtype": (
+            "float32" if args.fp32_trainable_params else "bfloat16"
+        ),
+        "optimizer_moment_dtype": (
+            "float32" if args.fp32_trainable_params else "bfloat16"
+        ),
+        "inference_checkpoint_dtype": "bfloat16",
+        "gpu": torch.cuda.get_device_name(device),
+    }
+    if rank == 0:
+        config_path = output_dir / "train_config.json"
+        tmp = config_path.with_suffix(".json.tmp")
+        tmp.write_text(
+            json.dumps(run_config, indent=2, ensure_ascii=False, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        os.replace(tmp, config_path)
+        print(json.dumps(run_config, indent=2, default=str), flush=True)
+
+    swanlab_run = None
+    if rank == 0:
+        if args.swanlab_mode == "cloud":
+            api_key = os.environ.get("SWANLAB_API_KEY")
+            # Prefer an explicit ephemeral key, while also supporting the cached
+            # machine credential installed during environment setup.
+            swanlab.login(api_key=api_key, save=False)
+        swanlab_run = swanlab.init(
+            project=args.swanlab_project,
+            workspace=args.swanlab_workspace,
+            experiment_name=args.swanlab_experiment,
+            description=(
+                f"Predictor-{args.predictor_variant} training; three adjacent "
+                "denoise transitions; 8xH100 DDP"
+            ),
+            tags=[
+                f"predictor-{args.predictor_variant}",
+                (
+                    "text-kv-only"
+                    if args.predictor_variant == "disca"
+                    else "context-prefeature"
+                ),
+                f"blocks-{args.source_blocks[0]}-{args.source_blocks[1]}",
+                f"fusion-{args.predictor_fusion_type}"[:20],
+                f"cond-{args.previous_condition_mode.replace('_step', 'step')}"[:20],
+                "batch16x8",
+            ],
+            config=run_config,
+            logdir=str(output_dir / "swanlab"),
+            mode=args.swanlab_mode,
+        )
+        print(
+            json.dumps(
+                {"swanlab_run_id": getattr(swanlab_run, "id", None)},
+                sort_keys=True,
+            ),
+            flush=True,
+        )
+
+    optimizer.zero_grad(set_to_none=True)
+    running = torch.zeros(18, device=device, dtype=torch.float64)
+    running_count = 0
+    # loss, hidden, velocity, batch_time, context_frames
+    try:
+        while global_step < args.max_steps:
+            epoch += 1
+            if bucket_sampler is not None:
+                bucket_sampler.set_epoch(epoch)
+            if distributed_sampler is not None:
+                distributed_sampler.set_epoch(epoch)
+            for item in loader:
+                if global_step >= args.max_steps:
+                    break
+                inputs, target_hidden, target_velocity = move_batch(
+                    item, device=device, dtype=dtype
+                )
+                started = time.perf_counter()
+                sync_gradients = (
+                    (micro_step + 1) % args.gradient_accumulation_steps == 0
+                )
+                sync_context = (
+                    torch.enable_grad()
+                    if sync_gradients
+                    else ddp.no_sync()
+                )
+                with sync_context:
+                    with torch.autocast(device_type="cuda", dtype=dtype):
+                        output = ddp(**inputs)
+                        hidden_loss = F.mse_loss(
+                            output["pred_hidden"].float(), target_hidden.float()
+                        )
+                        velocity_loss = F.mse_loss(
+                            output["pred_velocity"].float(), target_velocity.float()
+                        )
+                        loss = (
+                            args.hidden_weight * hidden_loss
+                            + args.velocity_weight * velocity_loss
+                        )
+                        scaled_loss = loss / args.gradient_accumulation_steps
+                    scaled_loss.backward()
+                micro_step += 1
+                gate_stats = output.get("gate_stats", {})
+                base_values = torch.tensor(
+                    [
+                        float(loss.detach()),
+                        float(hidden_loss.detach()),
+                        float(velocity_loss.detach()),
+                        time.perf_counter() - started,
+                        sum(item["context_frames"]) / len(item["context_frames"]),
+                    ],
+                    device=device,
+                    dtype=torch.float64,
+                )
+                gate_names = (
+                    "gate_p_mean",
+                    "gate_p_std",
+                    "gate_p_p10",
+                    "gate_p_p50",
+                    "gate_p_p90",
+                    "gate_p_near_zero",
+                    "gate_p_near_one",
+                )
+                gate_values = (
+                    torch.stack([gate_stats[name] for name in gate_names]).to(
+                        device=device, dtype=torch.float64
+                    )
+                    if gate_stats
+                    else torch.zeros(7, device=device, dtype=torch.float64)
+                )
+                atc_stats = output.get("atc_stats", {})
+                atc_names = (
+                    "delta_h_d_norm",
+                    "delta_h_c_norm",
+                    "gated_delta_h_c_norm",
+                    "transport_residual_norm",
+                    "anchor_distance_mean",
+                    "transport_attention_entropy",
+                )
+                atc_values = (
+                    torch.stack([atc_stats[name] for name in atc_names]).to(
+                        device=device, dtype=torch.float64
+                    )
+                    if atc_stats
+                    else torch.zeros(6, device=device, dtype=torch.float64)
+                )
+                running += torch.cat([base_values, gate_values, atc_values])
+                running_count += 1
+                del output, loss, scaled_loss, hidden_loss, velocity_loss
+                del inputs, target_hidden, target_velocity, item
+                if not sync_gradients:
+                    continue
+
+                grad_norm = torch.nn.utils.clip_grad_norm_(
+                    model.parameters(), args.grad_clip
+                )
+                optimizer.step()
+                if global_step == 0 or (
+                    args.resume is not None and global_step == int(state["global_step"])
+                ):
+                    validate_optimizer_precision(
+                        optimizer,
+                        fp32_trainable_params=args.fp32_trainable_params,
+                        require_state=True,
+                    )
+                scheduler.step()
+                optimizer.zero_grad(set_to_none=True)
+                global_step += 1
+
+                if global_step % args.log_every == 0 or global_step == 1:
+                    torch.cuda.synchronize(device)
+                    averaged = distributed_mean(running.clone())
+                    averaged /= running_count
+                    grad_value = torch.tensor(float(grad_norm), device=device)
+                    dist.all_reduce(grad_value, op=dist.ReduceOp.MAX)
+                    if rank == 0:
+                        record = {
+                            "global_step": global_step,
+                            "epoch": epoch,
+                            "loss": float(averaged[0]),
+                            "hidden_mse": float(averaged[1]),
+                            "velocity_mse": float(averaged[2]),
+                            "avg_micro_time_s": float(averaged[3]),
+                            "avg_context_frames": float(averaged[4]),
+                            "grad_norm_max": float(grad_value),
+                            "lr_fusion": optimizer.param_groups[0]["lr"],
+                            "lr_blocks": optimizer.param_groups[1]["lr"],
+                            "peak_memory_gib": torch.cuda.max_memory_allocated(device)
+                            / 2**30,
+                        }
+                        if args.predictor_arch == "atc" or args.predictor_fusion_type in {
+                            "token_gate_prev",
+                            "concat_residual_gate_prev",
+                        }:
+                            record.update(
+                                {
+                                    "gate_p_mean": float(averaged[5]),
+                                    "gate_p_std": float(averaged[6]),
+                                    "gate_p_p10": float(averaged[7]),
+                                    "gate_p_p50": float(averaged[8]),
+                                    "gate_p_p90": float(averaged[9]),
+                                    "gate_p_near_zero": float(averaged[10]),
+                                    "gate_p_near_one": float(averaged[11]),
+                                }
+                            )
+                        if args.predictor_arch == "atc":
+                            record.update(
+                                {
+                                    name: float(averaged[12 + index])
+                                    for index, name in enumerate(atc_names)
+                                }
+                            )
+                        with log_path.open("a", encoding="utf-8") as handle:
+                            handle.write(json.dumps(record, sort_keys=True) + "\n")
+                        swanlab.log(record, step=global_step)
+                        print(json.dumps(record, sort_keys=True), flush=True)
+                    running.zero_()
+                    running_count = 0
+
+                should_save = (
+                    global_step % args.save_every == 0
+                    or global_step == args.max_steps
+                )
+                if should_save:
+                    dist.barrier()
+                    if rank == 0:
+                        weights_path = (
+                            output_dir
+                            / f"predictor_step_{global_step:05d}.safetensors"
+                        )
+                        save_predictor_weights(
+                            model,
+                            weights_path,
+                            floating_dtype=torch.bfloat16,
+                        )
+                        if args.save_optimizer_state:
+                            save_training_state(
+                                output_dir / "training_latest.pt",
+                                {
+                                    "model": trainable_state_dict(model),
+                                    "optimizer": optimizer.state_dict(),
+                                    "scheduler": scheduler.state_dict(),
+                                    "global_step": global_step,
+                                    "micro_step": micro_step,
+                                    "epoch": epoch,
+                                    "args": vars(args),
+                                    "predictor_config": model.config_dict,
+                                    "weights_path": str(weights_path),
+                                },
+                            )
+                        prune_snapshots(output_dir, args.keep_snapshots)
+                    dist.barrier()
+    except BaseException as error:
+        if rank == 0 and swanlab_run is not None:
+            swanlab.finish(error=str(error))
+        raise
+    else:
+        if rank == 0 and swanlab_run is not None:
+            swanlab.finish()
+    finally:
+        dist.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()

train_predictor_v4_grouped_teacher_forcing.py

@@ -0,0 +1,825 @@
+#!/usr/bin/env python3
+"""Eight-GPU grouped teacher forcing using only the offline v4 dataset."""
+
+from __future__ import annotations
+
+import argparse
+import gc
+import json
+import os
+import random
+import time
+from pathlib import Path
+
+import swanlab
+import torch
+import torch.distributed as dist
+import torch.nn.functional as F
+from torch.nn.parallel import DistributedDataParallel as DDP
+from torch.optim import AdamW
+
+from hyvideo.commons.parallel_states import initialize_parallel_state
+from models.predictor_v2 import PredictorV2Config
+from models.predictor_v4 import HYWorldPlayPredictorV4
+from predictor_training.checkpoint import (
+    TRAINABLE_PREFIXES,
+    load_concat_fusion_initialization,
+    load_concat_residual_gate_initialization,
+    save_predictor_weights,
+    save_training_state,
+    trainable_state_dict,
+)
+from predictor_training.timestep_rollout_dataset import (
+    load_case_ids,
+    load_timestep_rollout_record,
+    load_timestep_rollout_records,
+    move_timestep_rollout_record,
+)
+from train_predictor_v4 import (
+    configure_model_precision,
+    initialize_runtime_state,
+    make_scheduler,
+    prune_snapshots,
+    validate_optimizer_precision,
+)
+
+
+DEFAULT_DATA_ROOT = Path("/mnt/local_nvme/zoubin/cz/hyworldplay_predictor_prefeature_v4")
+DEFAULT_CASES = Path("configs/rollout_overfit8_seed20260721_cases.jsonl")
+DEFAULT_TEACHER = Path(
+    "/mnt/s3files/s3-us-west2-default/zoubin/cz/checkpoints/hy_worldplay/"
+    "huggingface/hub/models--tencent--HY-WorldPlay/snapshots/"
+    "f4c29235647707b571479a69b569e4166f9f5bf8/ar_distilled_action_model/"
+    "diffusion_pytorch_model.safetensors"
+)
+DEFAULT_INIT_STATE = Path(
+    "checkpoints/"
+    "predictor_v4_prefeature_blocks1-52_fp32master_8gpu_"
+    "flr1e-4_blr1e-5_schedsteps2000_swarmup100_bwarmup100_swanlab/"
+    "training_latest.pt"
+)
+SOURCE_BLOCKS = (1, 52)
+EXPECTED_DENOISE_TIMESTEPS = (1000.0, 937.5, 833.3333129882812, 625.0)
+EXPECTED_DENOISE_SIGMAS = (1.0, 0.9375, 0.8333333134651184, 0.625, 0.0)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--training_mode",
+        choices=(
+            "grouped_teacher_forcing_offline_prefeature",
+            "detached_timestep_rollout_offline_ffff_targets",
+        ),
+        default="grouped_teacher_forcing_offline_prefeature",
+    )
+    parser.add_argument("--data_root", type=Path, default=DEFAULT_DATA_ROOT)
+    parser.add_argument("--cases_path", type=Path, default=DEFAULT_CASES)
+    parser.add_argument("--teacher_checkpoint", type=Path, default=DEFAULT_TEACHER)
+    parser.add_argument("--init_training_state", type=Path, default=DEFAULT_INIT_STATE)
+    parser.add_argument("--output_dir", type=Path, required=True)
+    parser.add_argument("--max_steps", type=int, default=1000)
+    parser.add_argument("--seed", type=int, default=20260721)
+    parser.add_argument("--fusion_lr", type=float, default=1e-4)
+    parser.add_argument(
+        "--predictor_fusion_type",
+        choices=(
+            "concat",
+            "projection_add",
+            "token_gate_prev",
+            "concat_residual_gate_prev",
+        ),
+        default="concat",
+    )
+    parser.add_argument("--gate_hidden_dim", type=int, default=256)
+    parser.add_argument("--gate_initial_probability", type=float, default=0.8)
+    parser.add_argument("--blocks_lr", type=float, default=1e-5)
+    parser.add_argument("--weight_decay", type=float, default=0.01)
+    parser.add_argument("--scheduler_warmup_steps", type=int, default=8)
+    parser.add_argument("--block_warmup_steps", type=int, default=8)
+    parser.add_argument("--hidden_weight", type=float, default=0.1)
+    parser.add_argument("--velocity_weight", type=float, default=1.0)
+    parser.add_argument("--grad_clip", type=float, default=1.0)
+    parser.add_argument(
+        "--gradient_checkpointing", action=argparse.BooleanOptionalAction, default=True
+    )
+    parser.add_argument(
+        "--fp32_trainable_params", action=argparse.BooleanOptionalAction, default=True
+    )
+    parser.add_argument("--save_every", type=int, default=100)
+    parser.add_argument("--keep_snapshots", type=int, default=3)
+    parser.add_argument("--log_every", type=int, default=1)
+    parser.add_argument("--resume", type=Path, default=None)
+    parser.add_argument("--swanlab_project", default="HY-WorldPlay-Predictor-v4")
+    parser.add_argument("--swanlab_workspace", default=None)
+    parser.add_argument("--swanlab_experiment", required=True)
+    parser.add_argument(
+        "--swanlab_mode",
+        choices=("cloud", "offline", "local", "disabled"),
+        default="cloud",
+    )
+    return parser.parse_args()
+
+
+def distributed_average(values: torch.Tensor) -> torch.Tensor:
+    dist.all_reduce(values, op=dist.ReduceOp.SUM)
+    values /= dist.get_world_size()
+    return values
+
+
+def load_stage1_initialization(
+    model: HYWorldPlayPredictorV4,
+    path: Path,
+) -> None:
+    """Load the Stage-1 FP32 master model while resetting optimizer/LR state."""
+    state = torch.load(path, map_location="cpu", weights_only=False)
+    if tuple(state["predictor_config"]["source_block_ids"]) != SOURCE_BLOCKS:
+        raise ValueError("Stage-1 initialization source blocks do not match")
+    saved_fusion_type = state.get("predictor_config", {}).get(
+        "predictor_fusion_type",
+        state.get("args", {}).get("predictor_fusion_type", "concat"),
+    )
+    target_fusion_type = model.predictor_config.predictor_fusion_type
+    if (
+        saved_fusion_type == "concat"
+        and target_fusion_type == "concat_residual_gate_prev"
+    ):
+        report = load_concat_residual_gate_initialization(model, state["model"])
+        print(
+            json.dumps(
+                {
+                    "fusion_initialization": "concat_residual_gate",
+                    "fresh_residual_key_count": len(
+                        report["fresh_residual_keys"]
+                    ),
+                },
+                sort_keys=True,
+            ),
+            flush=True,
+        )
+        return
+    if saved_fusion_type == "concat" and target_fusion_type != "concat":
+        report = load_concat_fusion_initialization(model, state["model"])
+        print(
+            json.dumps(
+                {
+                    "fusion_initialization": "concat_conversion",
+                    "discarded_concat_key_count": len(
+                        report["discarded_concat_keys"]
+                    ),
+                    "fresh_fusion_key_count": len(report["fresh_fusion_keys"]),
+                },
+                sort_keys=True,
+            ),
+            flush=True,
+        )
+        return
+    if saved_fusion_type != target_fusion_type:
+        raise ValueError(
+            "Stage-1 initialization fusion type does not match: "
+            f"saved={saved_fusion_type}, requested={target_fusion_type}"
+        )
+    result = model.load_state_dict(state["model"], strict=False)
+    missing_trainable = [
+        key for key in result.missing_keys if key.startswith(TRAINABLE_PREFIXES)
+    ]
+    if result.unexpected_keys or missing_trainable:
+        raise RuntimeError(
+            "Stage-1 initialization mismatch; "
+            f"unexpected={result.unexpected_keys}, missing={missing_trainable}"
+        )
+
+
+def assert_offline_timesteps(item: dict, device: torch.device) -> None:
+    expected = torch.tensor(
+        EXPECTED_DENOISE_TIMESTEPS, device=device, dtype=torch.float32
+    )
+    values = []
+    for step_id in range(4):
+        value = item["timesteps"][step_id]
+        if value.dtype != torch.float32 or value.numel() != 1:
+            raise TypeError(f"Offline timestep {step_id} is not one FP32 scalar")
+        values.append(value.reshape(1))
+    actual = torch.cat(values)
+    if not torch.equal(actual, expected):
+        raise RuntimeError(
+            "Offline denoise timesteps do not match the fixed four-step grid: "
+            f"actual={actual.detach().cpu().tolist()}"
+        )
+
+
+@torch.no_grad()
+def rebuild_offline_context_kv(
+    model: HYWorldPlayPredictorV4,
+    item: dict,
+) -> dict[int, dict[str, torch.Tensor]]:
+    """Run only v4's frozen projectors on saved BF16 Context prefeatures."""
+    with torch.autocast(device_type="cuda", dtype=torch.bfloat16):
+        rebuilt = model.context_projector(dict(item["context_prefeature"]))
+    result = {}
+    for block_id in SOURCE_BLOCKS:
+        result[block_id] = {
+            **dict(item["text_kv"][block_id]),
+            **rebuilt[block_id],
+            "context_valid_mask": item["context_prefeature"][block_id][
+                "context_valid_mask"
+            ],
+        }
+    return result
+
+
+def model_inputs(
+    *,
+    pair: dict,
+    item: dict,
+    context_kv: dict[int, dict[str, torch.Tensor]],
+) -> dict:
+    return {
+        "target_model_input": pair["model_input"],
+        "anchor_hidden": pair["anchor_hidden"],
+        "target_frame_condition": pair["frame_condition"],
+        "target_viewmats": item["target_viewmats"],
+        "target_Ks": item["target_Ks"],
+        "rope_temporal_size": item["rope_temporal_size"],
+        "start_rope_start_idx": item["start_rope_start_idx"],
+        "context_kv": context_kv,
+        "previous_chunk_hidden": pair["previous_chunk_hidden"],
+    }
+
+
+def empty_drift_metrics() -> dict[str, float]:
+    return {
+        "latent_drift_step2": 0.0,
+        "latent_drift_step3": 0.0,
+        "anchor_drift_step2": 0.0,
+        "anchor_drift_step3": 0.0,
+    }
+
+
+def detached_scheduler_step(
+    sample: torch.Tensor,
+    velocity: torch.Tensor,
+    *,
+    step_id: int,
+) -> torch.Tensor:
+    """Apply the exact four-step Euler update and truncate its graph."""
+    if step_id not in (1, 2):
+        raise ValueError(f"Detached rollout only advances after steps 1/2, got {step_id}")
+    sigmas = torch.tensor(
+        EXPECTED_DENOISE_SIGMAS,
+        device=sample.device,
+        dtype=torch.float32,
+    )
+    with torch.no_grad():
+        next_sample = sample.detach().float() + velocity.detach().float() * (
+            sigmas[step_id + 1] - sigmas[step_id]
+        )
+    if next_sample.requires_grad:
+        raise RuntimeError("Detached scheduler output unexpectedly requires gradients")
+    return next_sample
+
+
+def assert_offline_ffff_transitions(item: dict) -> None:
+    """Account for BF16 storage while checking the saved nominal trajectory."""
+    for step_id in (1, 2):
+        pair = item["teacher_forcing"][step_id]
+        expected = detached_scheduler_step(
+            pair["model_input"][:, :32],
+            pair["target_velocity"],
+            step_id=step_id,
+        )
+        target = item["teacher_forcing"][step_id + 1]["model_input"][:, :32]
+        error = (expected - target.float()).abs()
+        if float(error.max()) > 0.02 or float(error.mean()) > 0.002:
+            raise RuntimeError(
+                f"Offline FFFF transition {step_id}->{step_id + 1} does not "
+                f"match the fixed scheduler: max={float(error.max())}, "
+                f"mean={float(error.mean())}"
+            )
+
+
+def train_grouped_record(
+    *,
+    predictor: DDP,
+    predictor_model: HYWorldPlayPredictorV4,
+    optimizer: torch.optim.Optimizer,
+    item: dict,
+    args: argparse.Namespace,
+    device: torch.device,
+) -> dict[str, float]:
+    started = time.perf_counter()
+    assert_offline_timesteps(item, device)
+    if tuple(sorted(item["teacher_forcing"])) != (1, 2, 3):
+        raise ValueError("Grouped record does not contain all three supervision pairs")
+    context_kv = rebuild_offline_context_kv(predictor_model, item)
+
+    optimizer.zero_grad(set_to_none=True)
+    losses: list[torch.Tensor] = []
+    hidden_losses: list[torch.Tensor] = []
+    velocity_losses: list[torch.Tensor] = []
+    for step_id in (1, 2, 3):
+        pair = item["teacher_forcing"][step_id]
+        with torch.autocast(device_type="cuda", dtype=torch.bfloat16):
+            output = predictor(
+                **model_inputs(pair=pair, item=item, context_kv=context_kv)
+            )
+            hidden_loss = F.mse_loss(
+                output["pred_hidden"].float(), pair["target_hidden"].float()
+            )
+            velocity_loss = F.mse_loss(
+                output["pred_velocity"].float(), pair["target_velocity"].float()
+            )
+            step_loss = (
+                args.hidden_weight * hidden_loss
+                + args.velocity_weight * velocity_loss
+            )
+        losses.append(step_loss)
+        hidden_losses.append(hidden_loss.detach())
+        velocity_losses.append(velocity_loss.detach())
+        del output, hidden_loss, velocity_loss
+
+    objective_loss = torch.stack(losses).mean()
+    objective_loss.backward()
+    if any(parameter.grad is not None for parameter in predictor_model.context_projector.parameters()):
+        raise RuntimeError("Frozen Context projector unexpectedly received gradients")
+    grad_norm = torch.nn.utils.clip_grad_norm_(
+        predictor_model.parameters(), args.grad_clip
+    )
+    if not torch.isfinite(grad_norm):
+        raise FloatingPointError(f"Non-finite grad norm: {float(grad_norm)}")
+    optimizer.step()
+    result = {
+        "loss": float(objective_loss.detach()),
+        "hidden_mse_step1": float(hidden_losses[0]),
+        "hidden_mse_step2": float(hidden_losses[1]),
+        "hidden_mse_step3": float(hidden_losses[2]),
+        "velocity_mse_step1": float(velocity_losses[0]),
+        "velocity_mse_step2": float(velocity_losses[1]),
+        "velocity_mse_step3": float(velocity_losses[2]),
+        "grad_norm": float(grad_norm),
+        "record_time_s": time.perf_counter() - started,
+        **empty_drift_metrics(),
+    }
+    del context_kv, losses, hidden_losses, velocity_losses, objective_loss
+    return result
+
+
+def train_detached_rollout_record(
+    *,
+    predictor: DDP,
+    predictor_model: HYWorldPlayPredictorV4,
+    optimizer: torch.optim.Optimizer,
+    item: dict,
+    args: argparse.Namespace,
+    device: torch.device,
+) -> dict[str, float]:
+    """Roll out Predictor inputs while supervising against fixed offline FFFF outputs."""
+    started = time.perf_counter()
+    assert_offline_timesteps(item, device)
+    if tuple(sorted(item["teacher_forcing"])) != (1, 2, 3):
+        raise ValueError("Detached rollout record lacks one of steps 1/2/3")
+    assert_offline_ffff_transitions(item)
+    context_kv = rebuild_offline_context_kv(predictor_model, item)
+
+    optimizer.zero_grad(set_to_none=True)
+    losses: list[torch.Tensor] = []
+    hidden_losses: list[torch.Tensor] = []
+    velocity_losses: list[torch.Tensor] = []
+    latent_drifts: dict[int, torch.Tensor] = {}
+    anchor_drifts: dict[int, torch.Tensor] = {}
+
+    first_pair = item["teacher_forcing"][1]
+    rollout_latent = first_pair["model_input"][:, :32]
+    fixed_condition = first_pair["model_input"][:, 32:]
+    rollout_anchor = first_pair["anchor_hidden"]
+    for step_id in (1, 2, 3):
+        target_pair = item["teacher_forcing"][step_id]
+        if step_id > 1:
+            if rollout_latent.requires_grad or rollout_anchor.requires_grad:
+                raise RuntimeError(
+                    f"Step {step_id} received a gradient-connected rollout state"
+                )
+            latent_drifts[step_id] = F.mse_loss(
+                rollout_latent.float(),
+                target_pair["model_input"][:, :32].float(),
+            ).detach()
+            anchor_drifts[step_id] = F.mse_loss(
+                rollout_anchor.float(), target_pair["anchor_hidden"].float()
+            ).detach()
+        model_input = (
+            target_pair["model_input"]
+            if step_id == 1
+            else torch.cat([rollout_latent, fixed_condition], dim=1)
+        )
+        with torch.autocast(device_type="cuda", dtype=torch.bfloat16):
+            output = predictor(
+                **model_inputs(
+                    pair={
+                        **target_pair,
+                        "model_input": model_input,
+                        "anchor_hidden": rollout_anchor,
+                    },
+                    item=item,
+                    context_kv=context_kv,
+                )
+            )
+            hidden_loss = F.mse_loss(
+                output["pred_hidden"].float(), target_pair["target_hidden"].float()
+            )
+            velocity_loss = F.mse_loss(
+                output["pred_velocity"].float(), target_pair["target_velocity"].float()
+            )
+            step_loss = (
+                args.hidden_weight * hidden_loss
+                + args.velocity_weight * velocity_loss
+            )
+        losses.append(step_loss)
+        hidden_losses.append(hidden_loss.detach())
+        velocity_losses.append(velocity_loss.detach())
+        if step_id < 3:
+            rollout_anchor = output["pred_hidden"].detach()
+            rollout_latent = detached_scheduler_step(
+                rollout_latent, output["pred_velocity"], step_id=step_id
+            )
+        del output, hidden_loss, velocity_loss, model_input
+
+    objective_loss = torch.stack(losses).mean()
+    objective_loss.backward()
+    if any(parameter.grad is not None for parameter in predictor_model.context_projector.parameters()):
+        raise RuntimeError("Frozen Context projector unexpectedly received gradients")
+    grad_norm = torch.nn.utils.clip_grad_norm_(
+        predictor_model.parameters(), args.grad_clip
+    )
+    if not torch.isfinite(grad_norm):
+        raise FloatingPointError(f"Non-finite grad norm: {float(grad_norm)}")
+    optimizer.step()
+    result = {
+        "loss": float(objective_loss.detach()),
+        "hidden_mse_step1": float(hidden_losses[0]),
+        "hidden_mse_step2": float(hidden_losses[1]),
+        "hidden_mse_step3": float(hidden_losses[2]),
+        "velocity_mse_step1": float(velocity_losses[0]),
+        "velocity_mse_step2": float(velocity_losses[1]),
+        "velocity_mse_step3": float(velocity_losses[2]),
+        "latent_drift_step2": float(latent_drifts[2]),
+        "latent_drift_step3": float(latent_drifts[3]),
+        "anchor_drift_step2": float(anchor_drifts[2]),
+        "anchor_drift_step3": float(anchor_drifts[3]),
+        "grad_norm": float(grad_norm),
+        "record_time_s": time.perf_counter() - started,
+    }
+    del context_kv, losses, hidden_losses, velocity_losses
+    del latent_drifts, anchor_drifts, objective_loss, rollout_latent, rollout_anchor
+    return result
+
+
+def main() -> None:
+    args = parse_args()
+    if args.max_steps <= 0:
+        raise ValueError("max_steps must be positive")
+    if not 0.0 < args.gate_initial_probability < 1.0:
+        raise ValueError("gate_initial_probability must be in (0, 1)")
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is required")
+    if not {"RANK", "WORLD_SIZE", "LOCAL_RANK"}.issubset(os.environ):
+        raise RuntimeError("Launch grouped teacher forcing with torchrun")
+
+    rank = int(os.environ["RANK"])
+    world_size = int(os.environ["WORLD_SIZE"])
+    local_rank = int(os.environ["LOCAL_RANK"])
+    if world_size != 8:
+        raise ValueError(f"The overfit8 experiment requires 8 ranks, got {world_size}")
+    torch.cuda.set_device(local_rank)
+    device = torch.device("cuda", local_rank)
+    dist.init_process_group(backend="nccl", device_id=device)
+    initialize_parallel_state(sp=1)
+    initialize_runtime_state()
+    random.seed(args.seed + rank)
+    torch.manual_seed(args.seed + rank)
+    torch.cuda.manual_seed_all(args.seed + rank)
+
+    data_root = args.data_root.resolve()
+    cases_path = args.cases_path.resolve()
+    manifest_path = data_root / "train_eval_manifest.jsonl"
+    case_ids = load_case_ids(cases_path)
+    if len(case_ids) != world_size:
+        raise ValueError("Exactly one selected case per rank is required")
+    case_id = case_ids[rank]
+    record_root, records = load_timestep_rollout_records(
+        manifest_path, case_id=case_id
+    )
+    required = [
+        data_root,
+        cases_path,
+        manifest_path,
+        args.teacher_checkpoint.resolve(),
+        args.init_training_state.resolve(),
+    ]
+    if args.resume is not None:
+        required.append(args.resume.resolve())
+    for path in required:
+        if not path.exists():
+            raise FileNotFoundError(path)
+
+    output_dir = args.output_dir.resolve()
+    if rank == 0:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    dist.barrier()
+
+    model = HYWorldPlayPredictorV4(
+        PredictorV2Config(
+            source_block_ids=SOURCE_BLOCKS,
+            predictor_fusion_type=args.predictor_fusion_type,
+            gate_hidden_dim=args.gate_hidden_dim,
+            gate_initial_probability=args.gate_initial_probability,
+        )
+    )
+    # This selectively reads the two source blocks and fixed input/output modules
+    # from safetensors. It does not instantiate the Full Teacher model.
+    model.load_teacher_initialization(args.teacher_checkpoint.resolve())
+    configure_model_precision(
+        model,
+        device=device,
+        activation_dtype=torch.bfloat16,
+        fp32_trainable_params=args.fp32_trainable_params,
+    )
+    if args.resume is None:
+        load_stage1_initialization(model, args.init_training_state.resolve())
+    model.enable_gradient_checkpointing(args.gradient_checkpointing)
+    model.train()
+    if any(parameter.requires_grad for parameter in model.context_projector.parameters()):
+        raise RuntimeError("Context projector must remain frozen")
+
+    fusion_parameters = list(model.img_fusion.parameters()) + list(
+        model.residual_out.parameters()
+    )
+    block_parameters = [
+        parameter
+        for parameter in model.double_blocks.parameters()
+        if parameter.requires_grad
+    ]
+    optimizer = AdamW(
+        [
+            {"params": fusion_parameters, "lr": args.fusion_lr},
+            {"params": block_parameters, "lr": args.blocks_lr},
+        ],
+        betas=(0.9, 0.95),
+        weight_decay=args.weight_decay,
+    )
+    scheduler = make_scheduler(optimizer, args)
+    global_step = 0
+    epoch = 0
+    batch_in_epoch = 0
+    if args.resume is not None:
+        state = torch.load(args.resume, map_location="cpu", weights_only=False)
+        saved_args = state.get("args", {})
+        if saved_args.get("training_mode") != args.training_mode:
+            raise ValueError("Resume checkpoint training mode does not match")
+        if bool(saved_args.get("fp32_trainable_params")) != args.fp32_trainable_params:
+            raise ValueError("Resume precision mode does not match")
+        saved_fusion_type = state.get("predictor_config", {}).get(
+            "predictor_fusion_type",
+            saved_args.get("predictor_fusion_type", "concat"),
+        )
+        if saved_fusion_type != args.predictor_fusion_type:
+            raise ValueError("Resume fusion type does not match")
+        result = model.load_state_dict(state["model"], strict=False)
+        missing_trainable = [
+            key for key in result.missing_keys if key.startswith(TRAINABLE_PREFIXES)
+        ]
+        if result.unexpected_keys or missing_trainable:
+            raise RuntimeError(
+                "Resume model mismatch; "
+                f"unexpected={result.unexpected_keys}, missing={missing_trainable}"
+            )
+        optimizer.load_state_dict(state["optimizer"])
+        scheduler.load_state_dict(state["scheduler"])
+        global_step = int(state["global_step"])
+        epoch = int(state.get("epoch", 0))
+        batch_in_epoch = int(state.get("batch_in_epoch", 0))
+    validate_optimizer_precision(
+        optimizer,
+        fp32_trainable_params=args.fp32_trainable_params,
+        require_state=global_step > 0,
+    )
+    predictor = DDP(
+        model,
+        device_ids=[local_rank],
+        output_device=local_rank,
+        broadcast_buffers=False,
+        gradient_as_bucket_view=True,
+        find_unused_parameters=False,
+    )
+
+    detached_rollout = (
+        args.training_mode == "detached_timestep_rollout_offline_ffff_targets"
+    )
+    run_args = vars(args)
+    run_config = {
+        **run_args,
+        "data_root": str(data_root),
+        "cases_path": str(cases_path),
+        "output_dir": str(output_dir),
+        "world_size": world_size,
+        "case_ids": case_ids,
+        "records_per_rank": len(records),
+        "groups_per_optimizer_step_per_rank": 1,
+        "pairs_per_group": 3,
+        "source_blocks": list(SOURCE_BLOCKS),
+        "initialization": "stage1_step2000_model_only_optimizer_reset",
+        "runtime_full_teacher_loaded": False,
+        "teacher_checkpoint_usage": "selective_predictor_initialization_only",
+        "rollout_sidecar_loaded": False,
+        "context_source": "offline_bf16_prefeature_plus_offline_text_kv",
+        "context_projection": "frozen_v4_projector_once_per_group",
+        "targets": "offline_full_teacher_steps_1_2_3",
+        "input_state_source": (
+            "step1_offline_then_predictor_detached_rollout"
+            if detached_rollout else "offline_full_teacher_each_step"
+        ),
+        "anchor_source": (
+            "step1_offline_then_predictor_hidden_detached"
+            if detached_rollout else "offline_full_teacher_each_step"
+        ),
+        "timestep_graph": (
+            "P1|P2|P3_detached_state_rollout_one_mean_loss"
+            if detached_rollout
+            else "three_independent_offline_pairs_one_mean_loss"
+        ),
+        "offline_target_state_matches_rollout_input": not detached_rollout,
+        "offline_denoise_timesteps": list(EXPECTED_DENOISE_TIMESTEPS),
+        "offline_denoise_sigmas": list(EXPECTED_DENOISE_SIGMAS),
+        "offline_denoise_timestep_dtype": "float32",
+        "activation_dtype": "bfloat16",
+        "trainable_parameter_dtype": (
+            "float32" if args.fp32_trainable_params else "bfloat16"
+        ),
+    }
+    if rank == 0:
+        (output_dir / "train_config.json").write_text(
+            json.dumps(run_config, indent=2, ensure_ascii=False, default=str, sort_keys=True)
+            + "\n",
+            encoding="utf-8",
+        )
+        print(json.dumps(run_config, indent=2, ensure_ascii=False, default=str), flush=True)
+
+    swanlab_run = None
+    if rank == 0:
+        if args.swanlab_mode == "cloud":
+            swanlab.login(api_key=os.environ.get("SWANLAB_API_KEY"), save=False)
+        swanlab_run = swanlab.init(
+            project=args.swanlab_project,
+            workspace=args.swanlab_workspace,
+            experiment_name=args.swanlab_experiment,
+            description=(
+                "v4 detached timestep rollout with fixed offline FFFF targets; "
+                "offline prefeature path; no runtime Full Teacher"
+                if detached_rollout
+                else (
+                    "v4 grouped teacher forcing on overfit8; fully offline Stage-1 "
+                    "prefeature path; no runtime Full Teacher"
+                )
+            ),
+            tags=[
+                "predictor-v4",
+                "detached-rollout" if detached_rollout else "grouped-teacher",
+                "offline-prefeature",
+                "overfit8",
+                "8gpu",
+                f"fusion-{args.predictor_fusion_type}"[:20],
+            ],
+            config=run_config,
+            logdir=str(output_dir / "swanlab"),
+            mode=args.swanlab_mode,
+        )
+
+    log_path = output_dir / "train_log.jsonl"
+    metric_names = (
+        "loss",
+        "hidden_mse_step1",
+        "hidden_mse_step2",
+        "hidden_mse_step3",
+        "velocity_mse_step1",
+        "velocity_mse_step2",
+        "velocity_mse_step3",
+        "latent_drift_step2",
+        "latent_drift_step3",
+        "anchor_drift_step2",
+        "anchor_drift_step3",
+        "record_time_s",
+    )
+    try:
+        resume_epoch = epoch
+        resume_batch = batch_in_epoch
+        while global_step < args.max_steps:
+            order = list(range(len(records)))
+            random.Random(args.seed + rank + epoch * 100003).shuffle(order)
+            for loader_index, record_index in enumerate(order):
+                if epoch == resume_epoch and loader_index < resume_batch:
+                    continue
+                if global_step >= args.max_steps:
+                    break
+                cpu_item = load_timestep_rollout_record(
+                    record_root,
+                    records[record_index],
+                    replay_step=None,
+                    grouped_teacher_forcing=True,
+                    source_block_ids=SOURCE_BLOCKS,
+                )
+                item = move_timestep_rollout_record(cpu_item, device)
+                torch.cuda.reset_peak_memory_stats(device)
+                train_function = (
+                    train_detached_rollout_record
+                    if detached_rollout else train_grouped_record
+                )
+                metrics = train_function(
+                    predictor=predictor, predictor_model=model,
+                    optimizer=optimizer, item=item, args=args, device=device,
+                )
+                if global_step == 0:
+                    validate_optimizer_precision(
+                        optimizer,
+                        fp32_trainable_params=args.fp32_trainable_params,
+                        require_state=True,
+                    )
+                scheduler.step()
+                global_step += 1
+                batch_in_epoch = loader_index + 1
+
+                values = torch.tensor(
+                    [metrics[name] for name in metric_names],
+                    device=device,
+                    dtype=torch.float64,
+                )
+                averaged = distributed_average(values)
+                grad_max = torch.tensor(metrics["grad_norm"], device=device)
+                dist.all_reduce(grad_max, op=dist.ReduceOp.MAX)
+                if rank == 0 and (
+                    global_step % args.log_every == 0 or global_step == 1
+                ):
+                    record_log = {
+                        "global_step": global_step,
+                        "epoch": epoch,
+                        "batch_in_epoch": batch_in_epoch,
+                        **{
+                            name: float(averaged[index])
+                            for index, name in enumerate(metric_names)
+                        },
+                        "grad_norm_max": float(grad_max),
+                        "lr_fusion": optimizer.param_groups[0]["lr"],
+                        "lr_blocks": optimizer.param_groups[1]["lr"],
+                        "peak_memory_gib": torch.cuda.max_memory_allocated(device) / 2**30,
+                    }
+                    with log_path.open("a", encoding="utf-8") as handle:
+                        handle.write(json.dumps(record_log, sort_keys=True) + "\n")
+                    swanlab.log(record_log, step=global_step)
+                    print(json.dumps(record_log, sort_keys=True), flush=True)
+
+                should_save = (
+                    global_step % args.save_every == 0
+                    or global_step == args.max_steps
+                )
+                if should_save:
+                    dist.barrier()
+                    if rank == 0:
+                        weights_path = output_dir / f"predictor_step_{global_step:05d}.safetensors"
+                        save_predictor_weights(
+                            model, weights_path, floating_dtype=torch.bfloat16
+                        )
+                        save_training_state(
+                            output_dir / "training_latest.pt",
+                            {
+                                "model": trainable_state_dict(model),
+                                "optimizer": optimizer.state_dict(),
+                                "scheduler": scheduler.state_dict(),
+                                "global_step": global_step,
+                                "epoch": epoch,
+                                "batch_in_epoch": batch_in_epoch,
+                                "args": run_args,
+                                "predictor_config": model.config_dict,
+                                "weights_path": str(weights_path),
+                            },
+                        )
+                        prune_snapshots(output_dir, args.keep_snapshots)
+                    dist.barrier()
+                del cpu_item, item, metrics, values, averaged, grad_max
+                gc.collect()
+            epoch += 1
+            batch_in_epoch = 0
+            resume_batch = 0
+    except BaseException as error:
+        if rank == 0 and swanlab_run is not None:
+            try:
+                swanlab.finish(error=str(error))
+            except Exception:
+                pass
+        raise
+    else:
+        if rank == 0 and swanlab_run is not None:
+            swanlab.finish()
+    finally:
+        dist.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()