ControlProtocol(fix): Correct notification parsing per tmux source

tony · tony · commit fc9ac591f44c · 2025-12-06T11:53:32.000-06:00
why: Analysis against ~/study/c/tmux/ revealed 4 parsing bugs where
libtmux did not match the actual tmux protocol format.
what:
- Fix %extended-output: parse colon delimiter for payload (control.c:622)
- Fix %subscription-changed: parse all 5 fields before colon delimiter,
  handle "-" placeholders for session/window/pane scope (control.c:858-1036)
- Fix %session-changed: include session_name field (control-notify.c:165)
- Fix %exit: include optional reason field (client.c:425-427)
- Add 6 test fixtures using NamedTuple parametrization
diff --git a/src/libtmux/_internal/engines/control_protocol.py b/src/libtmux/_internal/engines/control_protocol.py
@@ -78,13 +78,17 @@ def _parse_notification(line: str, parts: list[str]) -> Notification:
     if tag == "%output" and len(parts) >= 3:
         kind = NotificationKind.PANE_OUTPUT
         data = {"pane_id": parts[1], "payload": " ".join(parts[2:])}
-    elif tag == "%extended-output" and len(parts) >= 4:
-        kind = NotificationKind.PANE_EXTENDED_OUTPUT
-        data = {
-            "pane_id": parts[1],
-            "behind_ms": parts[2],
-            "payload": " ".join(parts[3:]),
-        }
+    elif tag == "%extended-output" and len(parts) >= 3:
+        # Format: %extended-output %{pane_id} {age_ms} : {payload}
+        # The colon separates metadata from payload
+        colon_idx = line.find(" : ")
+        if colon_idx != -1:
+            kind = NotificationKind.PANE_EXTENDED_OUTPUT
+            data = {
+                "pane_id": parts[1],
+                "behind_ms": parts[2],
+                "payload": line[colon_idx + 3:],
+            }
     elif tag == "%pane-mode-changed" and len(parts) >= 2:
         kind = NotificationKind.PANE_MODE_CHANGED
         data = {"pane_id": parts[1], "mode": parts[2:]}
@@ -117,9 +121,10 @@ def _parse_notification(line: str, parts: list[str]) -> Notification:
     elif tag == "%window-pane-changed" and len(parts) >= 3:
         kind = NotificationKind.WINDOW_PANE_CHANGED
         data = {"window_id": parts[1], "pane_id": parts[2]}
-    elif tag == "%session-changed" and len(parts) >= 2:
+    elif tag == "%session-changed" and len(parts) >= 3:
+        # Format: %session-changed ${session_id} {session_name}
         kind = NotificationKind.SESSION_CHANGED
-        data = {"session_id": parts[1]}
+        data = {"session_id": parts[1], "session_name": " ".join(parts[2:])}
     elif tag == "%client-session-changed" and len(parts) >= 4:
         kind = NotificationKind.CLIENT_SESSION_CHANGED
         data = {
@@ -150,11 +155,24 @@ def _parse_notification(line: str, parts: list[str]) -> Notification:
     elif tag == "%continue" and len(parts) >= 2:
         kind = NotificationKind.CONTINUE
         data = {"pane_id": parts[1]}
-    elif tag == "%subscription-changed" and len(parts) >= 4:
-        kind = NotificationKind.SUBSCRIPTION_CHANGED
-        data = {"name": parts[1], "type": parts[2], "value": " ".join(parts[3:])}
+    elif tag == "%subscription-changed" and len(parts) >= 6:
+        # Format: %subscription-changed {name} ${session_id} @{window_id} {index} %{pane_id} : {value}
+        # Fields can be "-" for "not applicable". Colon separates metadata from value.
+        colon_idx = line.find(" : ")
+        if colon_idx != -1:
+            kind = NotificationKind.SUBSCRIPTION_CHANGED
+            data = {
+                "name": parts[1],
+                "session_id": parts[2] if parts[2] != "-" else None,
+                "window_id": parts[3] if parts[3] != "-" else None,
+                "window_index": parts[4] if parts[4] != "-" else None,
+                "pane_id": parts[5] if parts[5] != "-" else None,
+                "value": line[colon_idx + 3:],
+            }
     elif tag == "%exit":
+        # Format: %exit or %exit {reason}
         kind = NotificationKind.EXIT
+        data = {"reason": " ".join(parts[1:]) if len(parts) > 1 else None}
     elif tag == "%message" and len(parts) >= 2:
         kind = NotificationKind.MESSAGE
         data = {"text": " ".join(parts[1:])}
diff --git a/tests/test_engine_protocol.py b/tests/test_engine_protocol.py
@@ -203,6 +203,62 @@ def test_control_protocol_skips_unexpected_begin() -> None:
         expected_kind=NotificationKind.CONFIG_ERROR,
         expected_subset={"error": "/home/user/.tmux.conf:10: unknown option"},
     ),
+    NotificationFixture(
+        test_id="subscription_changed_session",
+        line="%subscription-changed mysub $1 - - - : session value here",
+        expected_kind=NotificationKind.SUBSCRIPTION_CHANGED,
+        expected_subset={
+            "name": "mysub",
+            "session_id": "$1",
+            "window_id": None,
+            "pane_id": None,
+            "value": "session value here",
+        },
+    ),
+    NotificationFixture(
+        test_id="subscription_changed_pane",
+        line="%subscription-changed mysub $1 @2 0 %3 : pane value",
+        expected_kind=NotificationKind.SUBSCRIPTION_CHANGED,
+        expected_subset={
+            "name": "mysub",
+            "session_id": "$1",
+            "window_id": "@2",
+            "window_index": "0",
+            "pane_id": "%3",
+            "value": "pane value",
+        },
+    ),
+    NotificationFixture(
+        test_id="extended_output_with_colon",
+        line="%extended-output %5 1500 : output with spaces",
+        expected_kind=NotificationKind.PANE_EXTENDED_OUTPUT,
+        expected_subset={
+            "pane_id": "%5",
+            "behind_ms": "1500",
+            "payload": "output with spaces",
+        },
+    ),
+    NotificationFixture(
+        test_id="session_changed_with_name",
+        line="%session-changed $1 my session name",
+        expected_kind=NotificationKind.SESSION_CHANGED,
+        expected_subset={
+            "session_id": "$1",
+            "session_name": "my session name",
+        },
+    ),
+    NotificationFixture(
+        test_id="exit_with_reason",
+        line="%exit server exited",
+        expected_kind=NotificationKind.EXIT,
+        expected_subset={"reason": "server exited"},
+    ),
+    NotificationFixture(
+        test_id="exit_no_reason",
+        line="%exit",
+        expected_kind=NotificationKind.EXIT,
+        expected_subset={"reason": None},
+    ),
 ]
 
 
