feat(boxen): C M6 #805 -- input_decoder cutover (replaces tb2 input layer)

[jsavin]

Summary

Phase C input decoder M6 -- THE CUTOVER. Replaces termbox2's input
layer in backend_tb2.c with the custom input_decoder built in
M1-M5. This is the milestone that actually fixes issue #805 in
production -- all prior milestones built and tested the decoder in
isolation against the inject-bytes test seam.

What changes

frontier-cli/boxen/backend_tb2.c (cutover):

• Add #include "input_decoder.h" and static input_decoder_t *g_decoder = NULL;
• tb2_init creates the decoder after tb_init(), obtaining the TTY fd via tb_get_fds() with a /dev/tty fallback per risk R1
• tb2_shutdown destroys the decoder BEFORE tb_shutdown() so any decoder writes (mouse-disable on destroy in a future milestone) land while raw mode is still active
• tb2_poll_event forwards directly to input_decoder_poll -- no translation layer; the decoder emits boxen_event_t directly
• Removed translate_key, translate_mod, translate_mouse, and the g_tb2_last_press double-click state struct. All subsumed by the decoder.
• Kept translate_attr and translate_color (rendering-side; untouched)
• Does NOT call tb_set_input_mode(TB_INPUT_MOUSE). Mouse starts disabled per plan section 5.1; M7 /mouse toggle will wire the on-demand enable.

frontier-cli/boxen/input_decoder.c (real read loop):

• Wire the real read(2) + select(2) path in input_decoder_poll. When tty_fd >= 0, block up to timeout_ms on select(2), then drain the pipe with non-blocking reads (collapses multi-byte escape sequences that arrive as one OS burst into one parse cycle, per plan section 4.4)
• Split poll body into dec_drain_buffer + orchestrator so the same parser loop runs both before and after the TTY fill
• EINTR/EAGAIN handled correctly; EOF on the TTY surfaces as BOXEN_ERR_IO so the REPL can shut down rather than spin
• Test seam (tty_fd == -1) preserved -- inject_bytes path unchanged; all 138 M1-M5 PTY-replay tests pass without modification

Merge gate (per plan section 7 + 9 + risk R4)

PTY-replay test run at HEAD:

$ make -C tests input_decoder_tests
$ ./tests/input_decoder_tests
[skip-summary] 0 of 138 tests are SKIP stubs
[test_report] input_decoder_tests: 138/138 tests passed

Test results at HEAD

Layer	Result
PTY-replay (tests/input_decoder_tests)	138/138 passed
Unit (./tools/run_headless_tests.sh)	964/964 passed
Integration (cd tests && make test-integration)	2186 passed, 21 failed, 207 skipped

The 21 integration failures match the develop baseline (pre-existing in html.*, tcp.*, startup -- unrelated to input handling).

Manual smoke status

The /auto runner cannot drive Terminal.app from inside the agent context. The plan section 6.4 manual smoke checklist remains for orchestrator (human-supervised) verification before merge:

• Type expression that produces multiple lines of output
• Up arrow walks history
• Option-Left / Option-Right jumps cursor by word (the original boxen REPL: mousewheel = history, option-arrows insert b/f literals #805 bug -- must NOT insert literal b / f)
• PgUp / PgDn scrolls output pane
• Ctrl-C twice exits cleanly
• Mouse-drag selects text natively (mouse mode off by default)
• Cmd-V paste of multi-line block appears at cursor without garbling (bracketed paste)

The PR #808 disaster occurred because tmux-only testing missed real Terminal.app behavior. This checklist MUST be exercised in Terminal.app (not tmux) before merge.

Risk disposition

• R1 (tb_get_fds availability): vendored termbox2 exports it. Fallback to /dev/tty is wired but should not fire on the supported platforms.
• R3 (mouse-enable timing window): not exercised in M6 (mouse stays off). Will surface in M7 when /mouse on lands.
• R4 (silent breakage repeat): mitigated by the 138-test PTY-replay matrix + the manual smoke checklist above. The /gate bar-raiser and security reviewers also run on this PR.

References

• Plan: planning/phase_c/INPUT_DECODER_PLAN.md sections 2.3, 5, 7 (M6 spec), 8.R1/R3/R4, 9
• M1: Phase C input decoder M1: PTY-replay harness + decoder stub #809 M2: Phase C input decoder M2: CSI cursor keys + modifier params + ESC disambiguation #810 M3: Phase C input decoder M3: SGR mouse + X10 fallback + burst-read robustness #811 M4: Phase C input decoder M4: Bracketed paste + BOXEN_EV_PASTE #812 M5: Phase C input decoder M5: Kitty keyboard protocol enable + decode #813

Closes #814
Closes #805

[jsavin]

/gate Report (post-fix)

Original gate verdict: PASS WITH NOTES (1 P1, 3 P2). The P1
documentation-accuracy finding has been addressed in this PR's second
commit (48112cb); the three P2s are deferred (logged in this PR
description as follow-up candidates -- not filed as issues yet pending
JES triage of which deserve standalone tracking).

Reviewer breakdown (gate ran in this sub-agent context without Agent
dispatch -- I applied the three reviewer lenses inline against the
diff and the surrounding files; full reasoning recorded below).

Tests

Layer	Result
Unit (./tools/run_headless_tests.sh)	964 / 964 passed at HEAD
Integration (cd tests && make test-integration)	2186 / 2207 passed; 21 failed (pre-existing baseline in html., tcp., startup -- unrelated to M6)
PTY-replay (./tests/input_decoder_tests)	138 / 138 passed at HEAD

Reviewers

• bar-raiser -- ran (always)
• security -- ran (always)
• concurrency -- ran (auto: matched path frontier-cli/**)
• swiftui -- skipped (excluded; pure C codebase)

---

P0 -- Blocking

(none)

P1 -- Important (addressed in commit 48112cb)

#	Finding	Files	Status
1	Threading-comment in backend_tb2.c:248-253 and input_decoder.c:1374-1382 mis-stated the GIL contract ("caller holds GIL" / "select blocks with GIL held"). Actual behavior: boxen_repl.c:2147-2152 (ADR-014, mirrors debugger_tui_main) drops the GIL via pthread_mutex_unlock(&frontier_gil) BEFORE calling boxen_poll_event. The decoder's select(2) runs with the GIL NOT held -- by design, so other Frontier threads make progress while the REPL is parked in poll. The single-owner invariant from input_decoder.h still holds (REPL thread is the only caller; other GIL-acquiring threads run UserTalk that never touches *dec). Code behavior was correct; only the comments mislead future readers.	frontier-cli/boxen/backend_tb2.c, frontier-cli/boxen/input_decoder.c	Fixed in 48112cb (comment-only)

P2 -- Deferred

#	Finding	File	Suggestion
1	dec_read_nonblocking stages reads through a 4 KiB stack buffer + memcpy; could read directly into dec->buf + dec->fill_len. Not a bug -- one elidable memcpy.	input_decoder.c (dec_read_nonblocking)	Defer unless profiling shows the copy matters.
2	The 4-iteration drain bound in input_decoder_poll is a reasonable starvation guard but its threat model isn't stated.	input_decoder.c (input_decoder_poll)	Add one-line comment naming the worst-case burst (~16 KiB paste arriving as >4 select rounds).
3	tb2_init falls back from tb_get_fds to open("/dev/tty") silently. If a future termbox2 update breaks tb_get_fds, the fallback would mask it.	backend_tb2.c (tb2_init)	Emit BOXEN_LOG_I when fd_was_opened_out becomes true, so the fallback path is visible in logs.

---

Verdict (post-fix): PASS

All P0/P1 resolved. P2s are tracked above for triage. Manual smoke
checklist (plan section 6.4) still pending human verification in
Terminal.app -- this is the PR #808 lesson and a hard merge gate.

Stats

• Files reviewed: 2 (backend_tb2.c, input_decoder.c)
• Findings: 0 P0, 1 P1 (fixed), 3 P2 (deferred)
• Reviewers ran: 3 of 4 configured (swiftui excluded by project config)