fix(cron): make the lifecycle guard total — sanitize at ingestion, not per-syscall

[kshitijk4poor]

Summary

The gateway lifecycle guard is now a total function — every input maps to a verdict, no input can crash it or stall it — by sanitizing untrusted bytes at three boundaries instead of catching exceptions at whichever syscall crashed that week.

Root cause of the class: the guard feeds untrusted byte streams (shlex-tokenized binaries, remote cat output) into OS-path and shell-text operations with no ingestion boundary. Each incident (#76762, #77703, #77780, #78256, #77729) got a per-callsite except; @tilllt's regression suite on #79454 (comment) showed 4 members of the class still open on merged main, and ~30 open community PRs each hot-fix another fragment.

Changes

• cron/lifecycle_guard.py — _expand_candidate_path(): single ingestion chokepoint for path candidates. Rejects NUL/empty tokens before any Path OS call and tolerates ValueError/RuntimeError/OSError from expanduser() (T1/T2, plus the HOME-unset launchd crash from fix(guard): never crash or false-positive on binary/executable paths #78056). Both _resolve_terminal_script_path and _resolve_script_path route through it.
• cron/lifecycle_guard.py — _sanitize_remote_script_text(): applies the local-read contract (NUL = binary = nothing to scan; >1 MiB = fail closed) to whatever any read_remote_script callback returns, at the recursion boundary. The guard stops trusting its callbacks — fix(terminal): skip binary content on referenced-script remote-read fallback (#77703) #79454 hardened one callback; this covers every current and future one (T3/T4).
• cron/lifecycle_guard.py — contains_gateway_lifecycle_command_or_referenced_script() is total by construction: direct regex scans (pure string ops) run first; the best-effort filesystem walk is wrapped so an unexpected failure logs a warning and falls back to the direct-scan verdict instead of breaking every terminal command until gateway restart.
• tools/terminal_tool.py — remote fallback reads head -c 1048577 instead of cat, so an oversized file never crosses the wire. One byte over budget is enough for the sanitizer to fail closed.
• tests/hermes_cli/test_gateway_restart_loop.py — tilllt's T1–T4 adopted as regression tests, plus an adversarial never-raises sweep (NUL paths, unset HOME, over-long paths) and a walk-crash fallback test.

Validation

tilllt's T1–T4 harness against merged main (49d8a155c) vs this branch:

Test	main @ 49d8a15	this PR
T1 ~\x00 candidate via terminal walk	crash (ValueError: embedded null byte)	pass (False)
T2 ~\x00 candidate via cron script path	crash (ValueError: embedded null byte)	pass (no raise)
T3 NUL binary from remote callback	false-positive block	pass (False)
T4 >1 MiB remote text	scanned unbounded	fail-closed (True)

Live probes (real imports, no guard mocks): all positive detections preserved — direct commands, launchctl kickstart/submit, nested wrapper scripts, remote-callback detection of a real lifecycle script; a 170 MB callback payload goes from a 30+ minute superlinear-shlex stall (#79838's field report) to a 0.02 s fail-closed verdict.

Tests: test_gateway_restart_loop.py 91 passed; test_terminal_tool.py + tests/cron/ 422 passed.

Credit

• @tilllt — the regression suite and boundary analysis on fix(terminal): skip binary content on referenced-script remote-read fallback (#77703) #79454 that mapped the residual class (T1–T4 adopted verbatim as tests).
• Field reports: terminal guard crashes with embedded null byte when remote-read fallback feeds binary content into the scanner (full-path ELF executables) #77703 (@Zedi), lifecycle_guard crashes on ValueError: embedded null byte from os.open — breaks all terminal commands #77780/lifecycle_guard crashes with ValueError: embedded null byte on 'python -m pip' commands (incomplete #76762 fix) #78256, fix(terminal): skip binary content on the referenced-script remote-read fallback (#77703) #77729, fix(guard): bound lifecycle-guard shlex scan against binary/oversized input #79838 (166 MB ELF stall), fix(guard): never crash or false-positive on binary/executable paths #78056 (HOME-unset launchd crash).

[monerostar]

Ubuntu 26.04 on linux-5800x.

Ran the PR's tests/hermes_cli/test_gateway_restart_loop.py against three trees:

tree	result
origin/main	7 failed, 84 passed (ValueError embedded null on tilde+NUL candidates; remote/oversized/adversarial cases)
sibling #80241	6 failed, 85 passed (still misses tilde-NUL walk, oversized remote fail-closed, total-function cases)
this PR	91 passed

Sanitizing at ingestion (_expand_candidate_path / remote text contract) is the right whole-class shape vs per-syscall catches. Prefer this over the narrower #80241 patch.

Looks good from Linux here.