fix mouse char bug on bwopencode exit

[Matt Snyder (maatthias)]

Summary

Fix stray mouse-report characters (e.g. 51;97;30M) landing on the shell
prompt when exiting bwopencode (and the other bw* wrappers) from a GTK4
terminal such as Ptyxis over SSH.

                                   ▄     
  █▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
  █  █ █  █ █▀▀▀ █  █ █    █  █ █  █ █▀▀▀
  ▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀

  Session   Fix exit escape chars & enable shift+enter newline
  Continue  opencode -s ses_abcd1234

[msnyder@runansible3 ansible]$ 51;19;11M

Description

Root cause

TUI tools enable all-motion mouse tracking (ESC[?1003h) and, on exit, send
"leave alternate screen" (ESC[?1049l) before "mouse tracking off"
(ESC[?1003l).

GTK4 synthesises a pointer-motion event whenever a window's layout changes,
even if the pointer has not moved (gtk/gtkwindow.c: "This fake motion
event is needed ... when the pointer didn't move but the layout changed").
Leaving the alternate screen is such a layout change in Ptyxis. VTE, still in
?1003 mode at that instant, encodes the synthetic event as an SGR mouse
report (ESC[<35;x;yM, or 51 if Ctrl is still held from Ctrl-D) and sends
it back over the two SSH hops. By the time it arrives, opencode has exited.

Because launch_sandbox() exec'd bwrap, the wrapper no longer existed
either, so the report was read by the login shell: the tty echoed ^[[<,
readline consumed the escape prefix, and 51;97;30M was left on the prompt.

This is not device-specific (reproduced with no mouse attached and hands off
the trackpad) and affects any GTK4/VTE terminal (Ptyxis, GNOME Terminal,
Black Box) over a link with non-trivial latency.

Fix

lib/bwrap_sandbox_lib.sh:

• launch_sandbox() now runs env -i ... bwrap ... as a foreground child
  instead of exec, captures the exit status and propagates it unchanged via
  exit "$_rc".
• New _restore_terminal() runs after the child exits, only when stdin and
  stdout are a tty:
  • emits a defensive reset: mouse modes 1000/1002/1003/1006 off, focus
    events (1004) off, bracketed paste (2004) off, pop kitty keyboard flags
    (CSI < u), show cursor (all no-ops if already in the default state, so
    safe after --exec commands);
  • stty -echo, then read-and-discard stdin until it has been quiet for
    BWRAP_TTY_DRAIN_SECS (default 0.3 s, host-env overridable for
    high-latency links), with an iteration cap so a misbehaving terminal
    cannot hang the wrapper;
  • restores saved termios, falling back to stty sane if the tool crashed
    while in raw mode.
• trap ':' INT around the wait so a Ctrl-C that kills the child does not
  also kill the wrapper before the terminal is restored. Children still
  receive SIGINT normally (trapped signals reset to default on exec).
• print_dry_run output drops the leading exec to match the real
  invocation; comments updated accordingly.

docs/bw-wrappers.md: new "Terminal restoration on exit" section.

Side effects / notes for reviewers

• One extra bash process per session (the wrapper stays resident).
• --die-with-parent is now anchored to the wrapper rather than the login
  shell. Equivalent in practice: the wrapper lives exactly as long as bwrap.
• ~0.3 s added to exit while the drain window elapses.
• Bonus: bwcodex's trap ... EXIT that removes the staged config.toml
  (bin/bwcodex:372) never fired under exec; it will now.
• Applies to all four wrappers (bwopencode, bwclaude, bwcodex,
  bwcopilot) since they share the library.
• Optional follow-up: file an upstream opencode issue asking it to send
  mouse-off before leaving the alt screen (or use ?1002, which VTE dedups).
  That would fix the root cause for everyone, but the wrapper fix is still
  worthwhile as defence in depth for all four tools.

Testing

Tested with gnome/ptyxis terminal on runansible3

Need more tests on other OS/terminals

Checklist

• Edit the sections above with relevant information
• Update in-repo documentation, if applicable
• Run pixi run -e dev lint locally (or wait for CI) — see .github/workflows/lint.yml
• Test the changes on a representative managed host (or runansible deployment)

[Copilot]

🟡 Changes recommended

Signal handling and background cleanup can disrupt termination or terminal state, while continued input can delay exit for minutes.

4 open issues

• Reset SIGTERM trap before launching sandbox child · New
• Restore terminal settings before resetting SIGINT handler · New
• Skip terminal cleanup when wrapper lacks foreground ownership · New
• Enforce overall cleanup deadline beyond byte and quiet limits · New

What changed in this PR

Prevents stray mouse reports from reaching the shell after sandboxed TUI tools exit.

Changes:

• Keeps wrappers running to restore terminal modes and drain delayed input.
• Adds a configurable drain timeout and documents exit cleanup.
• Updates dry-run output to match the foreground-child launch.

File	Description
lib/​bwrap_sandbox_lib.sh	Adds terminal cleanup and changes sandbox launch handling.
docs/​bw-wrappers.md	Documents terminal restoration and timeout configuration.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The resident wrapper breaks original-caller death propagation, allowing sandbox processes to remain running.

1 open issue

• Wrapper breaks --die-with-parent propagation after launcher exits · New

4 resolved since last review

• Restore terminal settings before resetting SIGINT handler
• Reset SIGTERM trap before launching sandbox child
• Enforce overall cleanup deadline beyond byte and quiet limits
• Skip terminal cleanup when wrapper lacks foreground ownership

_{Review effort: Balanced}