[turinglambdaai]

Summary

Fixes the implementation deliverables of #328 and #329 (both sourced from the #314 real-product journeys). Docs, the reference driver, a new CLI capability, and one runtime-behavior fix with red-green proof.

SIGTERM orderly exit (#329, finding 2)

The embedded Racket CS runtime maps SIGTERM to a Racket break; a GUI host swallows that break, so a packaged app hangs forever when terminated. Reproduced deterministically on a healthy packaged app (this is not only the wedged-startup case), while a plain racket process exits because its top level lets the break propagate.

The macOS host template (and the reference taskboard example) now install a self-pipe SIGTERM handler whose main-queue dispatch source runs NSApplication.terminate — reusing the existing applicationShouldTerminate orderly stop. The handler is installed at launch and re-asserted after the backend starts, because the runtime boot installs its own handlers and the last installation must win.

Red-green evidence: packaged app from the old template survived kill -TERM (still running at 0.0% CPU minutes later); packaged app from the new template exited orderly ~1 second after kill -TERM.

raco rivet acceptance --dry-run (#328, finding 3)

Loads and validates the manifest (shape, requirement coverage), resolves the current platform's suites and their executables, checks evidence path rules, and exits before launching any child. A hand-edited manifest with a syntax error now fails in seconds with a precise read error instead of minutes into a packaged suite. The report is flagged "dry-run": true with per-suite "dry-run" statuses — a validation record that must not feed raco rivet matrix. Tests cover the green path, no-execution proof, parse failure, missing executable, and evidence-path rejection.

Reference driver + docs (#328 findings 1–2, #329 findings 1–3)

native-ui-testing.md now documents the four silent desktop failures and the real exit contract:

1. AX focus writes are not focus — verify focus actually moved (or require an explicit key-view loop for toolbar-hosted fields).
2. IMEs swallow synthetic text — TIS ASCII-layout switch around keyboard phases, restore afterwards; helpers shipped in the reference driver.
3. Posted keys route to the user on shared desktops — frontmost guard before every posted key, fail fast (keyboardGuard in the reference driver).
4. AX elements die with their views — re-find from the live tree inside every bounded wait; the reference driver's event polling now re-probes instead of caching.
5. Exit semantics — quit Apple Event is the reliable orderly exit; SIGTERM/terminate/close-button can all be swallowed; second instances report false-positive frontmost with broken key routing. The reference driver exits through Cmd+Q (quitOrderly).
6. Wedged startup — the spin signature (backend answers, window never renders, threads at full CPU) with one bounded relaunch as the mitigation; wedges are runtime defects to report, never self-healing.

Validation

• raco test rivet/ rivet-cli/: 10205 passed (includes 6 new dry-run tests).
• raco test rivet/tests/documentation.rkt: 732 passed.
• swiftc -typecheck rivet/tests/native-ui/macos-ax.swift: green.
• raco rivet build in examples/taskboard: green (host template change compiles).
• SIGTERM red-green executed against freshly packaged scaffold apps (old template red, new template green).
• --dry-run smoke on a real project: valid manifest → exit 0 with per-suite listing; broken manifest → precise read error, exit 1.

Scope note

#329's startup-spin heisenbug is not fixed here (cannot be reproduced on demand; static analysis points at a GC thread-suspension rendezvous class of race inside the embedded Chez runtime — needs a spindump from a wedged instance). The issue keeps that finding open with the documented mitigation and the diagnostic evidence path; SIGTERM and the exit-semantics findings are resolved by this PR.