Context
Discovered during Course Builder demo video generation. VHS tape files (.tape) execute real shell commands, which means any tape that references long-running processes (model inference, API calls, database queries) will hang or fail during docgen vhs.
Problem
VHS renders by running an actual terminal session. Commands like:
Type ".venv/bin/python -m phase1.cli run --image satellite.png"
Enter
Sleep 12s
will actually execute phase1.cli run, which loads a 1GB+ DINOv2 model and runs GPU inference. Similarly, tapes that curl localhost:8080/... require a running server. The docgen vhs step hangs indefinitely with no timeout or feedback.
What we had to do
Rewrote all three VHS tapes to use echo for simulated output:
Type "echo '$ .venv/bin/python -m phase1.cli run --image satellite.png'"
Enter
Sleep 2s
Type "echo '[phase1] Loading DINOv2 model... done (2.3s)'"
Enter
This produces a realistic-looking terminal recording without executing real commands.
Recommendations
Severity
High — this is a silent hang with no error message. Users will assume docgen vhs is broken rather than realizing their tape commands are executing.
Context
Discovered during Course Builder demo video generation. VHS tape files (
.tape) execute real shell commands, which means any tape that references long-running processes (model inference, API calls, database queries) will hang or fail duringdocgen vhs.Problem
VHS renders by running an actual terminal session. Commands like:
will actually execute
phase1.cli run, which loads a 1GB+ DINOv2 model and runs GPU inference. Similarly, tapes thatcurl localhost:8080/...require a running server. Thedocgen vhsstep hangs indefinitely with no timeout or feedback.What we had to do
Rewrote all three VHS tapes to use
echofor simulated output:This produces a realistic-looking terminal recording without executing real commands.
Recommendations
docgen initscaffold and README that VHS tapes should useechofor demo output, not real commandsdocgen.yamloption likevhs.mock: truethat auto-wrapsType+Entersequences in echo simulationdocgen vhsper tape (default 120s) — if VHS hasn't completed, kill it and report which tape hungdocgen tape-lintcommand that warns about common pitfalls: commands containingpython,curl,npm start,docker, etc. that are likely to hangSeverity
High — this is a silent hang with no error message. Users will assume
docgen vhsis broken rather than realizing their tape commands are executing.