feat(stats): expose connected client geometry

Author: schickling-assistant

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+### 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 only and does not change attach, resize, negotiation, or DATA
+  ordering semantics.
+
 ### 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

@@ -233,7 +233,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 {
@@ -252,7 +256,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[];
@@ -267,6 +285,14 @@ 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.
+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

@@ -32,6 +32,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;
@@ -767,15 +768,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: 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;
@@ -810,6 +829,7 @@ export class PtyServer {
         total: attached + readOnly,
         attached,
         readOnly,
+        connections,
       },
       modes: {
         sgrMouse: this.sgrMouseMode,

tests/integration.test.ts

@@ -1384,6 +1384,61 @@ 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("reports exited process", async () => {
     const name = uniqueName();
     await startServer(name, "sh", ["-c", "exit 7"]);

tests/protocol.test.ts

@@ -258,15 +258,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);
     });
   });
 });