fix(stats): support legacy daemon responses

Author: schickling-assistant

docs/client.md

@@ -258,7 +258,7 @@ interface StatsResult {
   };
   clients: {
     total: number; attached: number; readOnly: number;
-    connections: Array<
+    connections?: Array<
       | {
           role: "writable";
           rows: number; cols: number;
@@ -290,8 +290,10 @@ point-in-time explanation of the current min-wins result, not an event stream;
 polling stats cannot order geometry changes relative to attached-session DATA.
 `lastRequestSequence` is a daemon-local counter for the writable connection's
 most recent attach or resize request, not a connection identity or timestamp.
-The daemon does not retain a durable client identity; socket and packet-parser
-state are transport internals and are not exposed.
+Older daemons omit `connections`; the aggregate counts remain authoritative and
+must not be reconstructed as an empty connection list. The daemon does not
+retain a durable client identity; socket and packet-parser state are transport
+internals and are not exposed.
 
 ## Session Interaction (CLI-oriented)
 

src/client.ts

@@ -314,7 +314,7 @@ export interface StatsResult {
     total: number;
     attached: number;
     readOnly: number;
-    connections: Array<
+    connections?: Array<
       | {
           role: "writable";
           rows: number;

src/server.ts

@@ -774,7 +774,7 @@ export class PtyServer {
 
     let attached = 0;
     let readOnly = 0;
-    const connections: StatsResult["clients"]["connections"] = [];
+    const connections: NonNullable<StatsResult["clients"]["connections"]> = [];
     for (const c of this.clients.values()) {
       if (c.readonly) {
         readOnly++;

tests/protocol.test.ts

@@ -17,6 +17,7 @@ import {
   decodeExit,
 } from "../src/protocol.ts";
 import { Buffer } from "node:buffer";
+import type { StatsResult } from "../src/client.ts";
 
 describe("protocol", () => {
   describe("encodePacket / PacketReader", () => {
@@ -281,5 +282,37 @@ describe("protocol", () => {
       expect(packets[0].type).toBe(MessageType.STATUS);
       expect(JSON.parse(packets[0].payload.toString())).toEqual(response);
     });
+
+    it("accepts an old-daemon STATUS response without connection details", () => {
+      const response = {
+        name: "legacy",
+        terminal: {
+          cols: 80,
+          rows: 24,
+          cursorX: 0,
+          cursorY: 0,
+          scrollbackUsed: 24,
+          scrollbackCapacity: 10024,
+        },
+        process: { alive: true, exitCode: null, pid: 123, resources: null },
+        daemon: { pid: 456, resources: null },
+        clients: { total: 2, attached: 2, readOnly: 0 },
+        modes: {
+          sgrMouse: false,
+          cursorHidden: false,
+          kittyKeyboard: false,
+          kittyKeyboardFlags: [],
+        },
+        uptimeSeconds: 10,
+        createdAt: "2026-07-31T00:00:00.000Z",
+      } satisfies StatsResult;
+
+      const reader = new PacketReader();
+      const packets = reader.feed(encodeStatusResponse(JSON.stringify(response)));
+      const decoded = JSON.parse(packets[0].payload.toString()) as StatsResult;
+
+      expect(decoded.clients).toEqual({ total: 2, attached: 2, readOnly: 0 });
+      expect(decoded.clients.connections).toBeUndefined();
+    });
   });
 });