@av-pi-studio/server 0.0.94 → 0.0.95

package/dist/daemon/bootstrap.js

@@ -482,7 +482,7 @@ export function startDaemon(opts) {
         restoreModesEnabled: true,
         projectConfigPath: (cwd) => join(cwd, "pi-studio.json"),
     }, getActiveSessions);
-    const terminalBinaryHandler = makeTerminalBinaryHandler(terminalManager);
+    const terminalBinaryHandler = makeTerminalBinaryHandler(terminalManager, broadcast, getActiveSessions);
     // ── Orchestration: schedules / chat / loops (real, disk-backed) ───────────────
     const scheduleExecutor = {
         async createAndPrompt(agentConfig, prompt) {

package/dist/terminal/screen-buffer.d.ts

@@ -9,6 +9,7 @@
  */
 export declare class ScreenBuffer {
     private readonly term;
+    private readonly serializeAddon;
     constructor(cols: number, rows: number, scrollback?: number);
     write(data: Uint8Array): void;
     resize(cols: number, rows: number): void;
@@ -16,6 +17,18 @@ export declare class ScreenBuffer {
     flush(): Promise<void>;
     /** The visible viewport as plain text, with trailing blank lines trimmed. */
     snapshotText(): string;
+    /**
+     * A reflowable redraw of the current screen — SGR colours/attributes and cursor position, not
+     * just text (`terminals.md` § Restore / snapshot, tier 2: the daemon's raw byte ring is
+     * approximate at a different width; this is the payload sent instead when both ends support
+     * it). Computed on demand, not maintained continuously, so an idle terminal costs nothing extra
+     * beyond what `capture`/`snapshotText` already require. Bounded to
+     * `RESTORE_SCROLLBACK_LINES` — verified empirically against `@xterm/addon-serialize@0.14.0`
+     * paired with `@xterm/headless@6.0.0` (no published peer range covers this pairing yet; the
+     * addon's actual API — reading `buffer.active` cells/modes — has been runtime-compatible across
+     * this xterm major since it predates the `@xterm/*` scoped rename).
+     */
+    serialize(): string;
     dispose(): void;
 }
 //# sourceMappingURL=screen-buffer.d.ts.map

package/dist/terminal/screen-buffer.js

@@ -2,9 +2,23 @@ import { createRequire } from "node:module";
 import stripAnsi from "strip-ansi";
 // `@xterm/headless` ships a UMD bundle whose `module.exports` Node's ESM loader cannot statically
 // read, so a named `import { Terminal }` resolves at type-check time but throws at runtime. Load it
-// through `createRequire` (CJS) to get the real `Terminal` constructor.
+// through `createRequire` (CJS) to get the real `Terminal` constructor. `@xterm/addon-serialize`
+// ships the same way (also a UMD bundle, no `exports` map in its `package.json`) and needs the
+// identical treatment (sprint-053/task-004) — expected, not a surprise discovered at runtime. Both
+// `import type`s above are erased at compile time (no runtime `import`, so no UMD-load failure);
+// they only give the two `require(...)` results below a real type instead of `any`.
 const require = createRequire(import.meta.url);
 const { Terminal } = require("@xterm/headless");
+const { SerializeAddon, } = require("@xterm/addon-serialize");
+/**
+ * Lines of scrollback history a reflowable `Restore` payload includes, on top of the viewport
+ * itself (`terminals.md` § Restore / snapshot, tier 2; `feature-panels-ui.md` § Reconnect/restore:
+ * "a visible-snapshot restore (bounded scrollback)"). A redraw needs the current screen, not the
+ * terminal's whole retained history (`ScreenBuffer`'s own `scrollback` constructor default is
+ * 1000 lines) replayed on every reattach — bounding this is what keeps the payload size
+ * predictable regardless of how long the terminal has been running.
+ */
+const RESTORE_SCROLLBACK_LINES = 200;
 /**
  * Server-side terminal screen model backed by `@xterm/headless` (features/terminals.md § capture).
  *
@@ -16,8 +30,17 @@ const { Terminal } = require("@xterm/headless");
  */
 export class ScreenBuffer {
     term;
+    serializeAddon;
     constructor(cols, rows, scrollback = 1000) {
         this.term = new Terminal({ cols, rows, scrollback, allowProposedApi: true });
+        this.serializeAddon = new SerializeAddon();
+        // `@xterm/addon-serialize`'s published types declare `activate(terminal: Terminal)` against
+        // `@xterm/xterm` (the browser package) specifically, so it is not structurally assignable to
+        // headless's own `ITerminalAddon` (which wants its OWN `Terminal` type) — even though the
+        // addon's real implementation only reads `buffer`/`cols`/`rows`, fields both `Terminal` types
+        // share, and works correctly headless (verified empirically: colours, cursor position, and
+        // text all round-trip — see `serialize()` below and its tests).
+        this.term.loadAddon(this.serializeAddon);
     }
     write(data) {
         this.term.write(Buffer.from(data));
@@ -48,6 +71,20 @@ export class ScreenBuffer {
         // translateToString already yields plain text; strip-ansi defends against any passthrough.
         return stripAnsi(lines.join("\n"));
     }
+    /**
+     * A reflowable redraw of the current screen — SGR colours/attributes and cursor position, not
+     * just text (`terminals.md` § Restore / snapshot, tier 2: the daemon's raw byte ring is
+     * approximate at a different width; this is the payload sent instead when both ends support
+     * it). Computed on demand, not maintained continuously, so an idle terminal costs nothing extra
+     * beyond what `capture`/`snapshotText` already require. Bounded to
+     * `RESTORE_SCROLLBACK_LINES` — verified empirically against `@xterm/addon-serialize@0.14.0`
+     * paired with `@xterm/headless@6.0.0` (no published peer range covers this pairing yet; the
+     * addon's actual API — reading `buffer.active` cells/modes — has been runtime-compatible across
+     * this xterm major since it predates the `@xterm/*` scoped rename).
+     */
+    serialize() {
+        return this.serializeAddon.serialize({ scrollback: RESTORE_SCROLLBACK_LINES });
+    }
     dispose() {
         this.term.dispose();
     }

package/dist/terminal/terminal-manager.d.ts

@@ -17,6 +17,13 @@ import { type PtyBackend } from "./pty-backend.js";
  */
 /** A subscriber sink receives fully-encoded binary terminal frames. */
 export type TerminalFrameSink = (frame: Uint8Array) => void;
+/**
+ * Tier negotiated per subscription (`terminals.md` § Restore / snapshot). `"basic"` is the raw
+ * byte-ring `Snapshot` (always available); `"reflowable"` is a `Restore` frame carrying
+ * `ScreenBuffer.serialize()` — correct at any client width, gated on both sides supporting it
+ * (`terminal-rpc.ts`'s negotiation). Exactly one of the two is ever sent per subscribe.
+ */
+export type RestoreMode = "basic" | "reflowable";
 export interface TerminalRuntimeEntry {
     slot: number;
     workspaceId: string;
@@ -76,10 +83,22 @@ export declare class TerminalManager {
     private readonly logger?;
     /** Rotating hand-out point in the one-byte slot space (see `nextFreeSlot`). */
     private slotCursor;
+    /** Exit listeners (`onTerminalExit`) — fired once per terminal, covering both `kill()` and a
+     * PTY exiting on its own (`exit`, a crash). See `onExit` below for the single call site. */
+    private readonly exitListeners;
     constructor(options?: TerminalManagerOptions);
     /** All live terminal runtime entries. */
     list(): TerminalRuntimeEntry[];
     get(slot: number): TerminalRuntimeEntry | undefined;
+    /**
+     * Subscribe to every terminal exit — self-exit (the `exit` command, a crash) or an explicit
+     * `kill()` — regardless of which session, if any, triggered it. Fires exactly once per
+     * terminal, after its entry has already been removed from `list()`. The daemon has no
+     * dedicated close opcode on the binary terminal stream (`onExit` below); this is the seam a
+     * caller uses to relay the fact out-of-band, e.g. `registerTerminalHandlers` broadcasting
+     * `terminals_update`. Returns an unsubscribe fn.
+     */
+    onTerminalExit(listener: (slot: number) => void): () => void;
     /**
      * Spawn a PTY in the backend, assign a slot, and track the runtime entry.
      *
@@ -90,10 +109,15 @@ export declare class TerminalManager {
      */
     createTerminal(options: CreateTerminalOptions): TerminalRuntimeEntry;
     /**
-     * Subscribe to a slot: emit a Snapshot frame (current screen) immediately, then live Output frames.
-     * Does NOT resize the PTY (passive attach must not claim size). Returns an unsubscribe fn.
+     * Subscribe to a slot: emit exactly one restore frame (current screen) immediately, then live
+     * Output frames. `restoreMode: "reflowable"` (default `"basic"`) sends a `Restore` frame
+     * carrying `ScreenBuffer.serialize()` instead of the raw byte-ring `Snapshot` — computed here,
+     * on subscribe, not maintained continuously (an idle terminal must cost nothing extra). Does
+     * NOT resize the PTY (passive attach must not claim size). Returns an unsubscribe fn.
      */
-    subscribe(slot: number, sink: TerminalFrameSink): () => void;
+    subscribe(slot: number, sink: TerminalFrameSink, opts?: {
+        restoreMode?: RestoreMode;
+    }): () => void;
     rename(slot: number, name: string): boolean;
     /** Forward input bytes to the PTY. */
     input(slot: number, bytes: Uint8Array): boolean;
@@ -127,9 +151,14 @@ export declare class TerminalManager {
  * whether `from` lands inside a sequence depends on where that sequence began, which may be
  * before `from` — the exact case a raw byte-offset cut produces.
  *
- * Bounded: if the sequence straddling `from` never terminates before `buffer.length`, drops to
- * `buffer.length` (nothing left of that unterminated tail is safe to replay) rather than scanning
- * past the buffer or emitting a partial sequence.
+ * Fallback (sprint-053/task-007): if the sequence straddling `from` never terminates before
+ * `buffer.length`, no position from `from` onward is provably safe — but returning `buffer.length`
+ * (dropping the entire retained region) is needlessly pessimistic for what is usually a few stray
+ * bytes, e.g. `cat` on a binary file leaving one unterminated DCS. Falls back to the naive cut
+ * (`from` itself) instead: the emulator eats whatever garbage remains of that one sequence on
+ * replay (bounded — at most one sequence's worth), which is strictly more readable than an empty
+ * snapshot. This fallback only applies when no safe boundary exists at all; a legitimate
+ * mid-sequence cut with a real boundary later in the buffer still returns that boundary unchanged.
  */
 export declare function safeReplayStart(buffer: Uint8Array, from: number): number;
 //# sourceMappingURL=terminal-manager.d.ts.map

package/dist/terminal/terminal-manager.js

@@ -1,6 +1,7 @@
 import { encodeTerminalFrame, nextFreeSlot, SLOT_SPACE } from "@av-pi-studio/protocol";
 import { createDefaultPtyBackend, resolveExecutable, } from "./pty-backend.js";
 import { ScreenBuffer } from "./screen-buffer.js";
+const textEncoder = new TextEncoder();
 /**
  * Grid bounds for any client-supplied size (`terminals.md` § PTY size ownership: "the daemon MUST
  * validate every requested size, whatever path it arrives on").
@@ -44,6 +45,9 @@ export class TerminalManager {
     logger;
     /** Rotating hand-out point in the one-byte slot space (see `nextFreeSlot`). */
     slotCursor = 1;
+    /** Exit listeners (`onTerminalExit`) — fired once per terminal, covering both `kill()` and a
+     * PTY exiting on its own (`exit`, a crash). See `onExit` below for the single call site. */
+    exitListeners = new Set();
     constructor(options = {}) {
         this.backend = options.backend ?? createDefaultPtyBackend();
         this.coalesceMs = options.coalesceMs ?? 4;
@@ -58,6 +62,18 @@ export class TerminalManager {
     get(slot) {
         return this.terminals.get(slot)?.entry;
     }
+    /**
+     * Subscribe to every terminal exit — self-exit (the `exit` command, a crash) or an explicit
+     * `kill()` — regardless of which session, if any, triggered it. Fires exactly once per
+     * terminal, after its entry has already been removed from `list()`. The daemon has no
+     * dedicated close opcode on the binary terminal stream (`onExit` below); this is the seam a
+     * caller uses to relay the fact out-of-band, e.g. `registerTerminalHandlers` broadcasting
+     * `terminals_update`. Returns an unsubscribe fn.
+     */
+    onTerminalExit(listener) {
+        this.exitListeners.add(listener);
+        return () => this.exitListeners.delete(listener);
+    }
     /**
      * Spawn a PTY in the backend, assign a slot, and track the runtime entry.
      *
@@ -132,15 +148,24 @@ export class TerminalManager {
         return entry;
     }
     /**
-     * Subscribe to a slot: emit a Snapshot frame (current screen) immediately, then live Output frames.
-     * Does NOT resize the PTY (passive attach must not claim size). Returns an unsubscribe fn.
+     * Subscribe to a slot: emit exactly one restore frame (current screen) immediately, then live
+     * Output frames. `restoreMode: "reflowable"` (default `"basic"`) sends a `Restore` frame
+     * carrying `ScreenBuffer.serialize()` instead of the raw byte-ring `Snapshot` — computed here,
+     * on subscribe, not maintained continuously (an idle terminal must cost nothing extra). Does
+     * NOT resize the PTY (passive attach must not claim size). Returns an unsubscribe fn.
      */
-    subscribe(slot, sink) {
+    subscribe(slot, sink, opts) {
         const managed = this.terminals.get(slot);
         if (!managed)
             throw new Error(`no terminal in slot ${slot}`);
-        // Snapshot first (rebuilds screen state), then live output.
-        sink(encodeTerminalFrame({ opcode: "Snapshot", slot, data: managed.screen.bytes() }));
+        // Exactly one restore-tier frame first (rebuilds screen state), then live output.
+        if (opts?.restoreMode === "reflowable") {
+            const data = textEncoder.encode(managed.screenModel.serialize());
+            sink(encodeTerminalFrame({ opcode: "Restore", slot, data }));
+        }
+        else {
+            sink(encodeTerminalFrame({ opcode: "Snapshot", slot, data: managed.screen.bytes() }));
+        }
         managed.subscribers.add(sink);
         return () => {
             managed.subscribers.delete(sink);
@@ -246,6 +271,8 @@ export class TerminalManager {
         // Notify subscribers the terminal closed (empty Output then drop). Clients treat an exited
         // terminal as closed; no dedicated close opcode exists in the binary protocol.
         managed.subscribers.clear();
+        for (const listener of this.exitListeners)
+            listener(managed.entry.slot);
     }
 }
 /**
@@ -254,7 +281,8 @@ export class TerminalManager {
  * the sequence's tail — parameter digits, an SGR/cursor final byte, an OSC payload — which the
  * emulator on replay consumes as garbage input instead of the printable text it actually is,
  * corrupting everything after it. `safeReplayStart` finds the nearest safe boundary at or after the
- * naive cut instead; `SnapshotRing.compact` is its only caller.
+ * naive cut instead; `SnapshotRing.compact` AND the oversized-single-chunk path in
+ * `SnapshotRing.append` both call it.
  */
 const ESC = 0x1b;
 const BEL = 0x07;
@@ -275,9 +303,14 @@ function startsStringSequence(byte) {
  * whether `from` lands inside a sequence depends on where that sequence began, which may be
  * before `from` — the exact case a raw byte-offset cut produces.
  *
- * Bounded: if the sequence straddling `from` never terminates before `buffer.length`, drops to
- * `buffer.length` (nothing left of that unterminated tail is safe to replay) rather than scanning
- * past the buffer or emitting a partial sequence.
+ * Fallback (sprint-053/task-007): if the sequence straddling `from` never terminates before
+ * `buffer.length`, no position from `from` onward is provably safe — but returning `buffer.length`
+ * (dropping the entire retained region) is needlessly pessimistic for what is usually a few stray
+ * bytes, e.g. `cat` on a binary file leaving one unterminated DCS. Falls back to the naive cut
+ * (`from` itself) instead: the emulator eats whatever garbage remains of that one sequence on
+ * replay (bounded — at most one sequence's worth), which is strictly more readable than an empty
+ * snapshot. This fallback only applies when no safe boundary exists at all; a legitimate
+ * mid-sequence cut with a real boundary later in the buffer still returns that boundary unchanged.
  */
 export function safeReplayStart(buffer, from) {
     if (from <= 0)
@@ -333,8 +366,9 @@ export function safeReplayStart(buffer, from) {
         }
     }
     // Ran off the end still inside an unterminated sequence (or a run of continuation bytes with no
-    // following lead byte) — nothing from `from` onward is a safe start.
-    return buffer.length;
+    // following lead byte) — no position is provably safe. Fall back to the naive cut rather than
+    // dropping everything (see the function doc comment's "Fallback" paragraph).
+    return from;
 }
 /**
  * Fraction of the cap the ring keeps when it compacts. The reclaimed headroom (the remaining

package/dist/terminal/terminal-rpc.d.ts

@@ -16,5 +16,5 @@ export interface TerminalRpcDeps {
 }
 export declare function registerTerminalHandlers(registry: HandlerRegistry, deps: TerminalRpcDeps, getActiveSessions: () => Iterable<Session>): void;
 /** Binary terminal-input frame handler for the frame dispatcher (Input/Resize opcodes). */
-export declare function makeTerminalBinaryHandler(manager: TerminalManager): BinaryHandler;
+export declare function makeTerminalBinaryHandler(manager: TerminalManager, broadcast: TerminalRpcDeps["broadcast"], getActiveSessions: () => Iterable<Session>): BinaryHandler;
 //# sourceMappingURL=terminal-rpc.d.ts.map

package/dist/terminal/terminal-rpc.js

@@ -5,6 +5,13 @@ export function registerTerminalHandlers(registry, deps, getActiveSessions) {
     // Per (session, slot) stream unsubscribers.
     const streamUnsubs = new Map();
     const key = (session, slot) => `${session.id}:${slot}`;
+    // A terminal exit — self-exit (`exit`, a crash) or `kill()` — always broadcasts the same
+    // `terminals_update` signal, unconditionally to every active session. This is the ONLY exit
+    // broadcast: `kill_terminal_request` below relies on it rather than sending its own, since
+    // `manager.kill()` invokes this listener synchronously and a second broadcast would duplicate it.
+    manager.onTerminalExit(() => {
+        deps.broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
+    });
     registry.register("list_terminals_request", () => ({
         type: "list_terminals_response",
         terminals: manager.list(),
@@ -40,10 +47,15 @@ export function registerTerminalHandlers(registry, deps, getActiveSessions) {
         const slot = Number(ctx.message.slot);
         const session = ctx.session;
         // Restore mode is honored only when the daemon advertises the feature AND the client advertised
-        // the reflowable-snapshot capability. Otherwise fall back to the basic snapshot (ignore mode).
+        // the reflowable-snapshot capability AND asked for it by name. The wire literal is exactly
+        // "reflowable" (sprint-053/task-004) — any other requested value (including a future/typo'd
+        // one) is served and echoed as "basic", so the response never names a tier that was not
+        // actually served.
         const requestedMode = ctx.message.restoreMode;
         const clientReflowable = session.supports("terminal_reflowable_snapshot");
-        const restoreMode = deps.restoreModesEnabled && clientReflowable ? (requestedMode ?? "basic") : "basic";
+        const restoreMode = deps.restoreModesEnabled && clientReflowable && requestedMode === "reflowable"
+            ? "reflowable"
+            : "basic";
         streamUnsubs.get(key(session, slot))?.(); // replace existing subscription
         try {
             // Resize BEFORE subscribing, using the grid the attaching client sent (if any).
@@ -62,9 +74,11 @@ export function registerTerminalHandlers(registry, deps, getActiveSessions) {
             //
             // Validation and the same-size no-op both live in `manager.resize` — the one choke point every
             // size path funnels through — so this passes the raw values straight through rather than
-            // growing a second, drifting copy of those rules here.
-            manager.resize(slot, Number(ctx.message.cols), Number(ctx.message.rows));
-            const unsub = manager.subscribe(slot, (frame) => session.sendBinary(frame));
+            // growing a second, drifting copy of those rules here. Broadcasts `terminals_update` when the
+            // grid actually changed (sprint-053/task-007), so an already-attached second client's stale
+            // belief gets corrected without it having to guess from a redundant `Resize` of its own.
+            resizeAndBroadcast(manager, deps.broadcast, getActiveSessions, slot, Number(ctx.message.cols), Number(ctx.message.rows));
+            const unsub = manager.subscribe(slot, (frame) => session.sendBinary(frame), { restoreMode });
             streamUnsubs.set(key(session, slot), unsub);
             // Echo the PTY's real size so the client can seed its belief instead of guessing. Without
             // this a reattaching client cannot know what it is attaching to, and has to send a blind
@@ -100,7 +114,6 @@ export function registerTerminalHandlers(registry, deps, getActiveSessions) {
     registry.register("kill_terminal_request", (ctx) => {
         const slot = Number(ctx.message.slot);
         const ok = manager.kill(slot);
-        deps.broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
         return { type: "kill_terminal_response", slot, ok };
     });
     registry.register("capture_terminal_request", (ctx) => {
@@ -135,8 +148,30 @@ export function registerTerminalHandlers(registry, deps, getActiveSessions) {
         };
     });
 }
+/**
+ * Apply a resize and broadcast the refreshed inventory to every active session, but only when the
+ * grid actually changed (sprint-053/task-007). An unknown slot, an invalid grid, and a same-size
+ * no-op must all stay silent — the binary `Resize` frame path is the hot path of every coalesced
+ * pane-divider drag, and a broadcast per intermediate frame would defeat that coalescing.
+ *
+ * Compares `TerminalManager.get(slot)` before and after rather than trusting `resize`'s boolean
+ * return (which is `true` for both an applied change and a same-size no-op) — `get` returns the
+ * live entry object, which `resize` mutates in place, so the cols/rows are captured into locals
+ * before the call rather than held as a stale reference to the same object.
+ */
+function resizeAndBroadcast(manager, broadcast, getActiveSessions, slot, cols, rows) {
+    const before = manager.get(slot);
+    const beforeCols = before?.cols;
+    const beforeRows = before?.rows;
+    if (!manager.resize(slot, cols, rows))
+        return;
+    const after = manager.get(slot);
+    if (after && (after.cols !== beforeCols || after.rows !== beforeRows)) {
+        broadcast(getActiveSessions(), { type: "terminals_update", terminals: manager.list() });
+    }
+}
 /** Binary terminal-input frame handler for the frame dispatcher (Input/Resize opcodes). */
-export function makeTerminalBinaryHandler(manager) {
+export function makeTerminalBinaryHandler(manager, broadcast, getActiveSessions) {
     return (_session, bytes) => {
         const frame = tryDecodeTerminalFrame(bytes);
         if (!frame)
@@ -144,7 +179,7 @@ export function makeTerminalBinaryHandler(manager) {
         if (frame.opcode === "Input")
             manager.input(frame.slot, frame.data);
         else if (frame.opcode === "Resize")
-            manager.resize(frame.slot, frame.cols, frame.rows);
+            resizeAndBroadcast(manager, broadcast, getActiveSessions, frame.slot, frame.cols, frame.rows);
     };
 }
 //# sourceMappingURL=terminal-rpc.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@av-pi-studio/server",
-  "version": "0.0.94",
+  "version": "0.0.95",
   "bin": {
     "pi-studio-daemon": "dist/daemon/main.js"
   },
@@ -24,10 +24,11 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@av-pi-studio/highlight": "^0.0.94",
-    "@av-pi-studio/protocol": "^0.0.94",
-    "@av-pi-studio/relay": "^0.0.94",
+    "@av-pi-studio/highlight": "^0.0.95",
+    "@av-pi-studio/protocol": "^0.0.95",
+    "@av-pi-studio/relay": "^0.0.95",
     "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@xterm/addon-serialize": "^0.14.0",
     "@xterm/headless": "^6.0.0",
     "bcryptjs": "^3.0.3",
     "lru-cache": "^11.5.1",