feat(stats): expose connected client geometry (#136)

* feat(stats): expose connected client geometry

* fix(stats): support legacy daemon responses

* fix(server): renegotiate when attached client peeks

* docs: describe PEEK size renegotiation

---------

Co-authored-by: Nathan Herald <me@nathanherald.com>

Author: schickling-assistant

CHANGELOG.md

@@ -15,6 +15,18 @@
   clients safely ignore the bounded unknown packet and retain raw-byte
   behavior.
 
+### Connected-client geometry introspection
+
+- `pty stats --json` and `queryStats()` retain their existing effective
+  terminal geometry and aggregate client counts, and now add anonymous
+  `clients.connections` details. Writable entries report their requested
+  rows/columns, last request sequence, and which min-wins axes they currently
+  constrain; readonly entries carry no geometry. This is point-in-time
+  observability and does not change attach/resize min-wins or DATA ordering
+  semantics. An attached client that switches to readonly via `PEEK` now
+  relinquishes its requested geometry, re-negotiating the effective size when
+  necessary.
+
 ### Read-only session listing
 
 - `listSessions()` and `pty list` are now strictly observational: they no

README.md

@@ -89,7 +89,7 @@ pty send myserver --paste "$(cat prompt.md)"           # wrap as bracketed paste
 
 pty stats                                 # live metrics for all sessions
 pty stats myserver                        # stats for a specific session
-pty stats --json                          # stats as JSON (includes CPU, memory, PIDs)
+pty stats --json                          # effective geometry, anonymous clients, CPU/memory/PIDs
 
 pty events myserver                       # follow events in real-time
 pty events --all                          # follow events from all sessions

docs/client.md

@@ -246,7 +246,11 @@ const plain = await peekScreen({ name: "myserver", plain: true }); // plain text
 
 ### `queryStats(name: string, timeoutMs?: number): Promise<StatsResult>`
 
-Query live metrics from a running session.
+Query live metrics from a running session without attaching. The matching
+`pty stats --json` command uses the same non-attaching STATUS request.
+`terminal.rows` and `terminal.cols` are the current effective shared geometry;
+`clients` includes aggregate counts plus anonymous connection details showing
+each writable client's requested size and which min-wins axes it constrains.
 
 ```typescript
 interface StatsResult {
@@ -265,7 +269,21 @@ interface StatsResult {
     pid: number;
     resources: ProcessResources | null;
   };
-  clients: { total: number; attached: number; readOnly: number };
+  clients: {
+    total: number; attached: number; readOnly: number;
+    connections?: Array<
+      | {
+          role: "writable";
+          rows: number; cols: number;
+          lastRequestSequence: number;
+          constrains: { rows: boolean; cols: boolean };
+        }
+      | {
+          role: "readonly";
+          constrains: { rows: false; cols: false };
+        }
+    >;
+  };
   modes: {
     sgrMouse: boolean; cursorHidden: boolean;
     kittyKeyboard: boolean; kittyKeyboardFlags: number[];
@@ -280,6 +298,16 @@ interface ProcessResources {
 }
 ```
 
+Connection details are anonymous and their order is unspecified. They are a
+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.
+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)
 
 These functions use `process.stdin`/`process.stdout` directly and may call `process.exit()`. They are re-exported for tools that want CLI-like behavior.

src/client.ts

@@ -314,6 +314,19 @@ export interface StatsResult {
     total: number;
     attached: number;
     readOnly: number;
+    connections?: Array<
+      | {
+          role: "writable";
+          rows: number;
+          cols: number;
+          lastRequestSequence: number;
+          constrains: { rows: boolean; cols: boolean };
+        }
+      | {
+          role: "readonly";
+          constrains: { rows: false; cols: false };
+        }
+    >;
   };
   modes: {
     sgrMouse: boolean;

src/server.ts

@@ -33,6 +33,7 @@ import {
   type SessionMetadata,
 } from "./sessions.ts";
 import { EventWriter, clearEvents, EventType, type EventRecord } from "./events.ts";
+import type { StatsResult } from "./client.ts";
 
 interface Client {
   socket: net.Socket;
@@ -690,7 +691,10 @@ export class PtyServer {
 
           case MessageType.PEEK: {
             client.readonly = true;
-            socket.write(encodeGeometry(this.terminal.rows, this.terminal.cols));
+            const resized = this.negotiateSize();
+            if (!resized) {
+              socket.write(encodeGeometry(this.terminal.rows, this.terminal.cols));
+            }
             const flags = packet.payload.length > 0 ? packet.payload.readUInt8(0) : 0;
             const plain = (flags & 1) !== 0;
             const full = (flags & 2) !== 0;
@@ -772,15 +776,33 @@ export class PtyServer {
     return prefix;
   }
 
-  private collectStats(): object {
+  private collectStats(): StatsResult {
     const buf = this.terminal.buffer.active;
     const meta = readMetadata(this.name);
 
     let attached = 0;
     let readOnly = 0;
+    const connections: NonNullable<StatsResult["clients"]["connections"]> = [];
     for (const c of this.clients.values()) {
-      if (c.readonly) readOnly++;
-      else if (c.attachSeq > 0) attached++;
+      if (c.readonly) {
+        readOnly++;
+        connections.push({
+          role: "readonly",
+          constrains: { rows: false, cols: false },
+        });
+      } else if (c.attachSeq > 0) {
+        attached++;
+        connections.push({
+          role: "writable",
+          rows: c.rows,
+          cols: c.cols,
+          lastRequestSequence: c.attachSeq,
+          constrains: {
+            rows: c.rows === this.terminal.rows,
+            cols: c.cols === this.terminal.cols,
+          },
+        });
+      }
     }
 
     const createdAt = meta?.createdAt ?? null;
@@ -815,6 +837,7 @@ export class PtyServer {
         total: attached + readOnly,
         attached,
         readOnly,
+        connections,
       },
       modes: {
         sgrMouse: this.sgrMouseMode,

tests/integration.test.ts

@@ -1384,6 +1384,107 @@ describe("STATUS message", () => {
     statsClient.destroy();
   });
 
+  it("reports anonymous client geometry and per-axis constraints", async () => {
+    const name = uniqueName();
+    await startServer(name, "cat");
+
+    const tall = await connect(name);
+    const tallReader = new PacketReader();
+    tall.write(encodeAttach(50, 80));
+    await waitForType(tall, tallReader, MessageType.SCREEN);
+
+    const wide = await connect(name);
+    const wideReader = new PacketReader();
+    wide.write(encodeAttach(30, 120));
+    await waitForType(wide, wideReader, MessageType.SCREEN);
+
+    const peeker = await connect(name);
+    const peekReader = new PacketReader();
+    peeker.write(encodePeek());
+    await waitForType(peeker, peekReader, MessageType.SCREEN);
+
+    const statsClient = await connect(name);
+    const statsReader = new PacketReader();
+    statsClient.write(encodeStatus());
+
+    const packet = await waitForType(statsClient, statsReader, MessageType.STATUS);
+    const stats = JSON.parse(packet.payload.toString());
+
+    expect(stats.terminal).toMatchObject({ rows: 30, cols: 80 });
+    expect(stats.clients.connections).toHaveLength(3);
+    expect(stats.clients.connections).toEqual(expect.arrayContaining([
+      {
+        role: "writable",
+        rows: 50,
+        cols: 80,
+        lastRequestSequence: 1,
+        constrains: { rows: false, cols: true },
+      },
+      {
+        role: "writable",
+        rows: 30,
+        cols: 120,
+        lastRequestSequence: 2,
+        constrains: { rows: true, cols: false },
+      },
+      {
+        role: "readonly",
+        constrains: { rows: false, cols: false },
+      },
+    ]));
+
+    tall.destroy();
+    wide.destroy();
+    peeker.destroy();
+    statsClient.destroy();
+  });
+
+  it("relinquishes a writable client's geometry constraints when it peeks", async () => {
+    const name = uniqueName();
+    await startServer(name, "cat", [], { rows: 50, cols: 120 });
+
+    const smaller = await connect(name);
+    const smallerReader = new PacketReader();
+    smaller.write(encodeAttach(30, 80));
+    await waitForType(smaller, smallerReader, MessageType.SCREEN);
+
+    const larger = await connect(name);
+    const largerReader = new PacketReader();
+    larger.write(encodeAttach(50, 120));
+    await waitForType(larger, largerReader, MessageType.SCREEN);
+
+    smaller.write(encodePeek());
+    await waitForType(smaller, smallerReader, MessageType.SCREEN);
+    const geometry = await waitForType(larger, largerReader, MessageType.GEOMETRY);
+    expect(geometry.payload.readUInt16BE(0)).toBe(50);
+    expect(geometry.payload.readUInt16BE(2)).toBe(120);
+
+    const statsClient = await connect(name);
+    const statsReader = new PacketReader();
+    statsClient.write(encodeStatus());
+    const packet = await waitForType(statsClient, statsReader, MessageType.STATUS);
+    const stats = JSON.parse(packet.payload.toString());
+
+    expect(stats.terminal).toMatchObject({ rows: 50, cols: 120 });
+    expect(stats.clients.connections).toEqual(expect.arrayContaining([
+      {
+        role: "readonly",
+        constrains: { rows: false, cols: false },
+      },
+      {
+        role: "writable",
+        rows: 50,
+        cols: 120,
+        lastRequestSequence: 2,
+        constrains: { rows: true, cols: true },
+      },
+    ]));
+
+    smaller.destroy();
+    larger.destroy();
+    statsClient.destroy();
+  });
+
   it("reports exited process", async () => {
     const name = uniqueName();
     await startServer(name, "sh", ["-c", "exit 7"]);

tests/protocol.test.ts

@@ -19,6 +19,7 @@ import {
   decodeExit,
 } from "../src/protocol.ts";
 import { Buffer } from "node:buffer";
+import type { StatsResult } from "../src/client.ts";
 
 describe("protocol", () => {
   describe("encodePacket / PacketReader", () => {
@@ -260,15 +261,28 @@ describe("protocol", () => {
 
     it("round-trips a STATUS response (JSON payload)", () => {
       const reader = new PacketReader();
-      const json = JSON.stringify({ name: "test", terminal: { cols: 80, rows: 24 } });
+      const response = {
+        name: "test",
+        terminal: { cols: 80, rows: 24 },
+        clients: {
+          total: 1,
+          attached: 1,
+          readOnly: 0,
+          connections: [{
+            role: "writable",
+            rows: 24,
+            cols: 80,
+            lastRequestSequence: 1,
+            constrains: { rows: true, cols: true },
+          }],
+        },
+      };
+      const json = JSON.stringify(response);
       const encoded = encodeStatusResponse(json);
       const packets = reader.feed(encoded);
       expect(packets).toHaveLength(1);
       expect(packets[0].type).toBe(MessageType.STATUS);
-      expect(JSON.parse(packets[0].payload.toString())).toEqual({
-        name: "test",
-        terminal: { cols: 80, rows: 24 },
-      });
+      expect(JSON.parse(packets[0].payload.toString())).toEqual(response);
     });
 
     it("round-trips an effective GEOMETRY packet", () => {
@@ -297,5 +311,37 @@ describe("protocol", () => {
       }
       expect(received).toBe("after-unknown");
     });
+
+    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();
+    });
   });
 });