# Repository guidance

## Restarting one worker

Python binds a module at process start, so a worker keeps serving the code it loaded. Run
`./check_stale.sh` before any stage run meant to prove a change. It exits non-zero and names the tmux
window for every worker older than its file (`decisions/identity-bbox.md#stale-worker-invalidates`).

**`tmux respawn-window -k` does not re-run the window's command.** It leaves a bare shell and the worker
stays down, silently. Restart by re-sending the `send-keys` line from `start_workers.sh` for that one
worker, then confirm on `/health` and with `check_stale.sh`:

```bash
M="export MIOPEN_USER_DB_PATH=$HOME/.config/miopen MIOPEN_SYSTEM_DB_PATH=$HOME/.config/miopen MIOPEN_FIND_MODE=2 && unset MIOPEN_FIND_ENFORCE"
tmux send-keys -t manga-workers:vision C-c
tmux send-keys -t manga-workers:vision "$M && source $PWD/.venv/bin/activate && python -m uvicorn worker_vision:app --app-dir $PWD --host 0.0.0.0 --port 8002" C-m
curl -s http://127.0.0.1:8002/health && ./check_stale.sh
```

The orchestrator's equivalent is `docker compose up -d --build orchestrator` on homesrv, because the image
bakes its source. That recreates the container, which drops any `docker cp`'d file such as
`audit_registry.py`.

## Video analysis

When diagnosing render motion, transitions, timing, or visual artifacts, use
`scripts/analyze_video_frames.sh` instead of manually seeking through the video.

```bash
scripts/analyze_video_frames.sh VIDEO [OUTPUT_DIR] \
  --window START:DURATION [--window START:DURATION ...]
```

The script creates:

- timestamped overview contact sheets sampled at 2 fps;
- scene-change frames and a `scene-timestamps.txt` index;
- optional dense 10-fps contact sheets for specified transition windows.

Inspect the overview first, then request dense windows around transitions or artifacts. Sampling and
scene sensitivity can be adjusted with `OVERVIEW_FPS`, `WINDOW_FPS`, and `SCENE_THRESHOLD`.

The generated files are analysis artifacts and belong in `/tmp` or another requested output directory;
do not commit them to the repository.