fix(smolmachines): bridge host SIGWINCH into the VM PTY (issue #82) #83
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: didericis/bot-bottle#83
Reference in New Issue
Block a user
Delete Branch "smolmachines-pty-resize-issue-82"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #82.
Diagnosis
smolvm 0.8.0 machine exec -tallocates an in-VM PTY but never forwards the host terminal's window size to it. The in-VM PTY starts at0 0, and any host-side resize during the session (tmux pane resize, terminal window resize) is dropped — the claude TUI keeps rendering for whatever tiny box it last saw.docker exec -itpropagates window-size changes automatically via SIGWINCH; smolvm doesn't.Reproduced:
smolvm machine exec --name <M> -- stty -F /dev/pts/0 sizereports0 0on a freshly-launched smolmachines bottle, even though the host terminal is a normal 80×24+.Workaround
A small Python wrapper,
claude_bottle/backend/smolmachines/pty_resize.py, interposes between the operator's terminal andsmolvm machine exec. On startup and every host SIGWINCH, it runs a side-channelsmolvm machine exec --name <M> -- sh -c 'for f in /dev/pts/*; do stty -F $f cols X rows Y; done'. The kernel delivers SIGWINCH to the foreground process group on the in-VM PTY's slave end when its size changes, so claude picks up the new dimensions without extra signalling.SmolmachinesBottle.claude_argvprepends[sys.executable, -m, claude_bottle.backend.smolmachines.pty_resize, <machine>, --, ...]to the existing smolvm argv in TTY mode. Non-TTY mode (provisioning shell-outs that happen to go through this method) skips the wrapper — no PTY to resize.The wrapper composes correctly with the dashboard's
_build_resume_argv_with_fallbackshell-wrap: the split-at-claudetoken still finds the right position because the wrapper's prefix wraps the entire smolvm-exec framing.Tests
tests/unit/test_smolmachines_pty_resize.py(new): argv parsing, the side-channel command shape (cols/rows order, for-loop over/dev/pts/*), and_read_winsize's fallback across stdin/stdout/stderr including the ironic case where the smolvm-allocated PTY reports0 0and gets skipped.tests/unit/test_smolmachines_bottle.py: TTY-mode assertions now unwrap the pty_resize prefix; newTestClaudeArgvNoTTYclass locks the non-TTY skip.636 unit tests pass.
Removable
This whole module can come out once smolvm grows native SIGWINCH forwarding. Upstream report not filed yet — followup tracked separately.
How much overhead does this add?
Measured on my box against a running claude-bottle smolvm machine:
At rest (no resize): zero CPU. The wrapper Python process just blocks on
proc.wait()— no signal arrives, no syscalls run. Memory cost is one Python interpreter, ~12 MB RSS.Per SIGWINCH event: the side-channel
smolvm machine exec -- sh -c 'for f in /dev/pts/*; do stty -F $f cols X rows Y; done'takes about 50 ms in steady state (10 iters: 110, 53, 53, 49, 53, 56, 49, 41, 55, 51 ms — first is colder, rest are warm). That's almost entirely smolvm setup + libkrun exec channel round-trip, not the stty work.Frequency: SIGWINCH is human-driven — fires only when the terminal window or tmux pane changes size. Typical session: zero events. Active drag-to-resize: maybe 5-10 events bursted over a second or two while the user is dragging, then nothing.
Worst case (someone holding the corner and dragging the window slowly for a few seconds): a queue of 50 ms exec calls trailing the drag, settling within ~100 ms of when they stop. Imperceptible against the 50–200 ms claude TUI redraw it triggers anyway.
If the per-event cost ever becomes load-bearing we could keep a long-lived
smolvm machine execsession open over a pipe and poke it withsttycommands instead of paying smolvm startup every time — but at one event per resize and 50 ms per event, the complexity isn't worth it.The dashboard's launch path crashed inside tmux but worked outside it. Root cause: `python -m claude_bottle.backend.smolmachines.pty_resize` needs the `claude_bottle` package on `sys.path`, which by default comes from cwd. The outside-tmux path is `subprocess.run(...)` — inherits the dashboard process's cwd (the repo root, where `claude_bottle/` lives), so the import resolves. The inside-tmux path is `tmux split-window / respawn-pane <argv>`, and tmux opens the new pane with the pane's OWN cwd, not the cwd of the process invoking split-window. If the operator started their tmux pane anywhere outside the repo (typical: `$HOME`), the wrapper hit `ModuleNotFoundError: No module named 'claude_bottle'` and tmux closed the pane immediately. Sidestep the cwd dependence by invoking the wrapper as `python <absolute-path-to-pty_resize.py>` instead of `python -m <dotted-path>`. The wrapper has no `claude_bottle.*` imports — it's stdlib-only — so it runs as a standalone script anywhere on the filesystem. The absolute path comes from `pty_resize.__file__` at module-load time. Tests: - `test_pty_resize_wrapper_prefix`: updated to assert the absolute-script-path shape rather than the `-m <dotted>` shape. - `test_no_wrapper_when_tty_false`: the substring check now uses `any("pty_resize" in a for a in argv)` instead of string-joining (so the absolute path's "pty_resize.py" filename match still catches a regression). 636 unit tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>@@ -27,0 +33,4 @@# with ModuleNotFoundError whenever the operator's tmux pane was# started from anywhere outside the claude-bottle repo. Absolute# path sidesteps the cwd dependence (the wrapper has no# claude_bottle.* imports, so it runs as a standalone script).This wasn't the core issue, so I don't know if this logic is true. But it doesn't hurt/might be true, I think?
@@ -0,0 +148,4 @@# the side-channel writes a fresh config.json without# collision, and the in-VM PTY is sized before claude has# finished rendering its first frame. daemon=True so the# timer doesn't block exit when the child finishes quickly.comment is redundant with comment for the constant
Fixed
Both addressed in follow-up
b3c6d66(direct to main).@@ -27,0 +33,4 @@# with ModuleNotFoundError whenever the operator's tmux pane was# started from anywhere outside the claude-bottle repo. Absolute# path sidesteps the cwd dependence (the wrapper has no# claude_bottle.* imports, so it runs as a standalone script).Fair call. The tmux-pane-cwd hypothesis was just a guess that turned out not to be the actual bug (libkrun's bringup race was), and I never went back to verify it. Rewrote the comment in
b3c6d66to drop the speculation and just state the operative reason: the wrapper is self-contained (noclaude_bottle.*imports), so an absolute-path invocation works regardless of cwd. Same one-line_PTY_RESIZE_SCRIPT = _pty_resize.__file__line, leaner justification.@@ -0,0 +148,4 @@# the side-channel writes a fresh config.json without# collision, and the in-VM PTY is sized before claude has# finished rendering its first frame. daemon=True so the# timer doesn't block exit when the child finishes quickly.Right — collapsed in
b3c6d66to a one-liner pointing at_STARTUP_SYNC_DELAY_SECplus thedaemon=Trueoperational note. The libkrun-race + warm-VM-timing explanation now lives only on the constant.