ilo run: cap runtime + stdout to prevent runaway programs (#5ar)

[danieljohnmorris]

Summary

A mandelbrot persona run (2026-05-20) missed a col=col+1 loop increment, spun in an infinite loop, and produced 165 MB of stdout before the harness killed the process. The transcript was useless to the agent: a wall of dots with no signal about what went wrong. This PR adds two production-safety guards so the next runaway aborts cleanly with a structured diagnostic the agent can act on.

• --max-runtime SECS (default 60) caps wall-clock; over budget raises ILO-R016 and exits 1.
• --max-output-bytes BYTES (default ~100 MB) caps stdout; over budget raises ILO-R017 and exits 1.

Both flags accept 0 to disable for batch / training workloads. Defaults are well above any legitimate agent task (real ones finish under 10 s and produce kilobytes), so well-behaved programs are unaffected — pinned by a regression test.

Repro before / after

Before:

$ ilo 'main>n;n=0;wh true{n=+n 1};n'
^C    -- after burning CPU until the operator notices

After:

$ ilo --max-runtime 1 --json 'main>n;n=0;wh true{n=+n 1};n'
{"error":{"code":"ILO-R016","hint":"infinite loop is the most common cause - check loop variables increment, recursion has a base case, or pass `--max-runtime N` if a legitimate program needs longer.","message":"wall-clock runtime exceeded 1000 ms (--max-runtime 1)"}}
$ echo $?
1

Output budget:

$ ilo --max-output-bytes 100 'main>n;n=0;wh true{prnt n;n=+n 1};0'
0
1
2
...
{"error":{"code":"ILO-R017","hint":"a loop printing without a break or increment is the most common cause - check `prnt` calls inside `wh`/`fa` bodies. raise the cap with `--max-output-bytes N` if a legitimate program needs more.","message":"stdout output exceeded 100 bytes (--max-output-bytes)"}}

What's in the diff

Five commits, each one coherent change:

1. runtime_guard module + diagnostic registry entries - new src/runtime_guard.rs with install() / record_output() / abort_with(). Watchdog thread polls elapsed at 100 ms granularity. Registry entries for ILO-R016 and ILO-R017 explain the most common cause and override flag.
2. CLI: --max-runtime / --max-output-bytes flags - global flags wired through cli/args.rs and main.rs. Both the explicit Cmd::Run arm and the bare-positional dispatch install the guard before executing user code.
3. Engines: output accounting at every print site - three sites total (Builtin::Prnt in interpreter, OP_PRT in VM, jit_prt in Cranelift). Each charges len() + 1 (for the newline) against the budget before printing.
4. Tests: cover R016 + R017 across VM and JIT engines - six subprocess tests (one per engine x guard, plus happy path and 0 disables). Subprocess is required because the guard calls process::exit(1) after writing the diagnostic — no graceful return path on purpose.
5. Docs sync - SPEC.md gets the two new CLI rows + a production-safety paragraph; ai.txt regenerates via build.rs; skills/ilo/ilo-agent.md gets a "Runtime + output caps" section; skills/ilo/ilo-errors.md adds R016 / R017 one-liners.

Why a watchdog thread instead of cancellation tokens

Threading a cancellation token through every engine's eval loop (tree, VM, Cranelift JIT) is a much bigger change for a guard that only fires on already-broken programs. A watchdog that writes a diagnostic and exit(1)s is async-signal-safe enough and ships today. Output accounting at the three print sites is the symmetric tight loop covered without touching the eval dispatch.

Test plan

• cargo test --release --features cranelift — full suite green (3322 + 199 + ... + 1, no failures)
• cargo fmt --check — clean
• cargo clippy --release --features cranelift --all-targets -- -D warnings — clean
• Manual smoke tests on every engine (VM default, JIT) — infinite loops abort cleanly, output overflows abort cleanly, happy-path triangle-number example runs

Follow-ups

• Site docs (cli.md, diagnostics.md) ship in the separate ilo-lang/site repo with the same wording.
• Persona harness should treat ILO-R016 / ILO-R017 as a signal to look at loop variables before re-dispatching (no code change needed — already what the diagnostic hint says).

[codecov]

Codecov Report

❌ Patch coverage is 96.87500% with 6 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/runtime_guard.rs	93.10%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!

[danieljohnmorris]

Closing — keep-both rebase produces broken Rust syntax (install_runtime_guard call mangled). Will reimplement against post-drain main per the same path as #503/#504/#494.

[danieljohnmorris]

Superseded by fresh-impl PR (in flight on feature/-v2 branch). The original PR's keep-both rebase produced broken Rust that can't be unstuck without manual brace surgery. The v2 PR is a clean reimpl against current main.