fix(smolmachines): bridge host SIGWINCH into the VM PTY (issue #82)

`smolvm 0.8.0 machine exec -t` allocates an in-VM PTY but never
forwards the host terminal's window size — the PTY starts at
`0 0` and host resizes (tmux pane resize, terminal window
resize) go unnoticed, so the claude TUI inside a smolmachines
bottle renders for whatever tiny box it last saw and ignores
operator resizes. `docker exec -it` propagates window-size
changes automatically; smolvm doesn't.

Workaround: a small Python wrapper
(`backend/smolmachines/pty_resize.py`) that interposes between
the operator's terminal and `smolvm machine exec`. It spawns
smolvm as a child, traps host SIGWINCH, and on every resize
(plus once at startup) runs a side-channel
`smolvm 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 in-VM foreground process group when the slave
PTY's size changes, so claude picks up the new dimensions
without extra signalling.

`SmolmachinesBottle.claude_argv` prepends
`[sys.executable, -m, claude_bottle.backend.smolmachines.
pty_resize, <machine>, --, ...]` to the existing smolvm argv
in TTY mode. Non-TTY mode (provisioning shell-outs) skips the
wrapper — no PTY to resize.

The wrapper survives the dashboard's
`_build_resume_argv_with_fallback` shell-wrap because the
split-at-`claude` token still finds the right position — the
wrapper's prefix wraps the entire smolvm-exec framing.

Tests:
- `test_smolmachines_pty_resize.py` (new): argv parsing, the
  side-channel command shape (cols/rows / for-loop over
  /dev/pts/*), and `_read_winsize`'s fallback across
  stdin/stdout/stderr including the smolvm-allocated-PTY-
  reports-`0 0` ironic case.
- `test_smolmachines_bottle.py`: updated TTY-mode assertions
  to unwrap the pty_resize prefix; added `TestClaudeArgvNoTTY`
  to lock the non-TTY skip.

636 unit tests pass.

Removable when smolvm grows native SIGWINCH forwarding.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/unit/test_smolmachines_bottle.py

@@ -5,10 +5,15 @@ directly (it spawns claude inside a tmux pane rather than as a
 child of the current process), so the argv shape is the
 non-trivial part. `exec_claude` is a thin wrapper around the same
 builder + `subprocess.run`; we lock the shape here.
+
+The TTY-mode argv is wrapped in the pty_resize helper (issue #82
+workaround); we assert both the wrapper presence and the wrapped
+smolvm argv shape. Non-TTY mode skips the wrapper.
 """
 
 from __future__ import annotations
 
+import sys
 import unittest
 
 from claude_bottle.backend.smolmachines.bottle import SmolmachinesBottle
@@ -22,9 +27,30 @@ def _bottle(prompt_path: str | None = None, **env: str) -> SmolmachinesBottle:
     )
 
 
-class TestClaudeArgv(unittest.TestCase):
-    def test_minimal_argv_no_prompt(self):
+def _unwrap(argv: list[str]) -> list[str]:
+    """Strip the pty_resize wrapper from the front of a TTY-mode
+    argv, return the inner smolvm argv. Mirrors what the kernel
+    sees inside the wrapper's `subprocess.Popen`."""
+    idx = argv.index("--")
+    return argv[idx + 1:]
+
+
+class TestClaudeArgvWrapped(unittest.TestCase):
+    """TTY-mode argv: pty_resize wrapper + inner smolvm exec."""
+
+    def test_pty_resize_wrapper_prefix(self):
         argv = _bottle().claude_argv([])
+        self.assertEqual(
+            [
+                sys.executable, "-m",
+                "claude_bottle.backend.smolmachines.pty_resize",
+                "claude-bottle-dev-abc", "--",
+            ],
+            argv[:5],
+        )
+
+    def test_minimal_inner_argv_no_prompt(self):
+        argv = _unwrap(_bottle().claude_argv([]))
         self.assertEqual(
             [
                 "smolvm", "machine", "exec", "--name",
@@ -40,19 +66,19 @@ class TestClaudeArgv(unittest.TestCase):
         )
 
     def test_appends_passed_args_after_claude(self):
-        argv = _bottle().claude_argv(
+        argv = _unwrap(_bottle().claude_argv(
             ["--dangerously-skip-permissions", "--continue"],
-        )
-        # The claude tail is at the end of the argv, after the
-        # `runuser -u node --` switch.
+        ))
         self.assertEqual(
             ["claude", "--dangerously-skip-permissions", "--continue"],
             argv[argv.index("claude"):],
         )
 
     def test_appends_prompt_file_flag_when_set(self):
-        argv = _bottle("/home/node/.claude-bottle-prompt.txt").claude_argv(
-            ["--dangerously-skip-permissions"],
+        argv = _unwrap(
+            _bottle("/home/node/.claude-bottle-prompt.txt").claude_argv(
+                ["--dangerously-skip-permissions"],
+            )
         )
         self.assertEqual(
             [
@@ -72,20 +98,12 @@ class TestClaudeArgv(unittest.TestCase):
         argv = _bottle("").claude_argv(["--continue"])
         self.assertNotIn("--append-system-prompt-file", argv)
 
-    def test_tty_false_drops_it_flags(self):
-        argv = _bottle().claude_argv([], tty=False)
-        self.assertNotIn("-i", argv)
-        self.assertNotIn("-t", argv)
-
     def test_guest_env_forwarded_as_e_flags(self):
-        argv = _bottle(
+        argv = _unwrap(_bottle(
             None,
             HTTPS_PROXY="http://127.0.0.1:1234",
             NO_PROXY="localhost",
-        ).claude_argv([])
-        # `-e K=V` pairs land before the `--`. Order isn't
-        # guaranteed across dict iterations on older Pythons, but
-        # both must appear.
+        ).claude_argv([]))
         self.assertIn("-e", argv)
         self.assertIn("HTTPS_PROXY=http://127.0.0.1:1234", argv)
         self.assertIn("NO_PROXY=localhost", argv)
@@ -103,5 +121,20 @@ class TestClaudeArgv(unittest.TestCase):
         )
 
 
+class TestClaudeArgvNoTTY(unittest.TestCase):
+    """`tty=False` paths skip the pty_resize wrapper — there's no
+    PTY whose SIGWINCH we'd need to bridge."""
+
+    def test_no_wrapper_when_tty_false(self):
+        argv = _bottle().claude_argv([], tty=False)
+        self.assertEqual("smolvm", argv[0])
+        self.assertNotIn("pty_resize", " ".join(argv))
+
+    def test_tty_false_drops_it_flags(self):
+        argv = _bottle().claude_argv([], tty=False)
+        self.assertNotIn("-i", argv)
+        self.assertNotIn("-t", argv)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_smolmachines_pty_resize.py

@@ -0,0 +1,117 @@
+"""Unit: smolmachines pty_resize bridge (issue #82).
+
+Locks down the parts of the wrapper we can test without spawning
+real children or signalling — argument parsing, the side-channel
+`smolvm machine exec` argv shape, and TTY-resolution fallback
+across stdin/stdout/stderr.
+"""
+
+from __future__ import annotations
+
+import io
+import unittest
+from unittest.mock import patch
+
+from claude_bottle.backend.smolmachines import pty_resize
+
+
+class TestPushSize(unittest.TestCase):
+    def test_emits_for_loop_over_all_pts_devices(self):
+        # The shell `for f in /dev/pts/*` handles multiple
+        # interactive sessions in the same VM (rare but cheap).
+        # Per-PTY `stty -F ... 2>/dev/null` swallows EBADF when a
+        # session has already exited.
+        with patch.object(pty_resize.subprocess, "run") as run:
+            pty_resize._push_size("claude-bottle-m", 50, 200)
+        argv = run.call_args.args[0]
+        self.assertEqual(
+            ["smolvm", "machine", "exec", "--name",
+             "claude-bottle-m", "--", "sh", "-c"],
+            argv[:8],
+        )
+        # cols / rows land in the order stty wants them.
+        self.assertIn("cols 200", argv[8])
+        self.assertIn("rows 50", argv[8])
+        self.assertIn("for f in /dev/pts/*", argv[8])
+
+    def test_swallows_subprocess_failures(self):
+        # `check=False` + DEVNULL streams: a side-channel failure
+        # mustn't break the operator's session.
+        with patch.object(
+            pty_resize.subprocess, "run",
+            side_effect=OSError("boom"),
+        ):
+            with self.assertRaises(OSError):
+                pty_resize._push_size("m", 24, 80)
+        # The wrapper-level `sync()` is what swallows; `_push_size`
+        # itself raises so the test above documents that. The
+        # signal-handler-side `sync` in main wraps in try/except
+        # via the `if size is None: return` guard for the
+        # no-TTY case (no separate try needed because subprocess
+        # already has check=False; only fcntl.ioctl raising would
+        # surface, and _read_winsize handles that).
+
+
+class TestReadWinsize(unittest.TestCase):
+    def test_returns_none_when_no_tty(self):
+        # Patch ioctl to always OSError — simulates the case where
+        # none of stdin/stdout/stderr is a TTY (e.g., tests, piped
+        # automation).
+        with patch.object(
+            pty_resize.fcntl, "ioctl",
+            side_effect=OSError("ENOTTY"),
+        ):
+            self.assertIsNone(pty_resize._read_winsize())
+
+    def test_returns_first_tty_size(self):
+        # First fd that responds with a non-zero size wins —
+        # matches the "different surfaces give different TTYs"
+        # invariant noted in the module docstring.
+        import struct
+
+        calls: list[int] = []
+
+        def fake_ioctl(fd, req, buf):
+            calls.append(fd)
+            if fd == 0:
+                raise OSError("stdin not a tty")
+            return struct.pack("hhhh", 42, 137, 0, 0)
+
+        with patch.object(pty_resize.fcntl, "ioctl", side_effect=fake_ioctl):
+            self.assertEqual((42, 137), pty_resize._read_winsize())
+
+    def test_skips_zero_sizes(self):
+        # A TTY that reports `0 0` (the smolvm-allocated PTY's
+        # initial state, ironically) shouldn't be used as the
+        # source of truth — keep probing fallback fds.
+        import struct
+
+        responses = iter([
+            struct.pack("hhhh", 0, 0, 0, 0),       # stdin: zero
+            struct.pack("hhhh", 24, 80, 0, 0),     # stdout: real
+        ])
+
+        def fake_ioctl(fd, req, buf):
+            return next(responses)
+
+        with patch.object(pty_resize.fcntl, "ioctl", side_effect=fake_ioctl):
+            self.assertEqual((24, 80), pty_resize._read_winsize())
+
+
+class TestMainArgvParsing(unittest.TestCase):
+    def test_missing_separator_returns_error_exit_code(self):
+        # No `--` between machine name and inner argv.
+        with patch.object(pty_resize.sys, "stderr", new=io.StringIO()) as err:
+            rc = pty_resize.main(["claude-bottle-m", "smolvm", "machine"])
+        self.assertEqual(2, rc)
+        self.assertIn("usage:", err.getvalue())
+
+    def test_too_few_args_returns_error_exit_code(self):
+        with patch.object(pty_resize.sys, "stderr", new=io.StringIO()):
+            self.assertEqual(2, pty_resize.main([]))
+            self.assertEqual(2, pty_resize.main(["m"]))
+            self.assertEqual(2, pty_resize.main(["m", "--"]))
+
+
+if __name__ == "__main__":
+    unittest.main()