@av-pi-studio/server 0.0.93 → 0.0.95

package/dist/agent/providers/pi/agent.js

@@ -18,6 +18,7 @@ export const PI_CAPABILITIES = {
     supportsReasoningStream: true,
     supportsToolInvocations: true,
     supportsSteering: true,
+    supportsExtensionUi: true,
 };
 /** Build Pi argv, appending (never replacing) the system prompt and optional `--mcp-config`. */
 export function buildPiArgs(base, opts) {
@@ -41,12 +42,54 @@ function modelIdFrom(model) {
         return rec.name;
     return undefined;
 }
+/** Dialog methods block for a client answer; every other extension UI method is fire-and-forget
+ * (docs/rpc.md § Extension UI Protocol). The single place the blocking set is encoded — a future Pi
+ * release that adds a method only ever touches this constant. */
+const DIALOG_METHODS = new Set(["select", "confirm", "input", "editor"]);
+/**
+ * Translate a raw Pi `extension_ui_request` event onto the provider-neutral UI channel
+ * (features/extension-ui-rpc.md § Provider contract extension). All Pi-specific knowledge — which
+ * methods block, surface-key namespacing, clear-by-omission, the `timeout` field name — lives here;
+ * nothing above this adapter learns Pi's vocabulary.
+ *
+ * Surface-key namespacing is mandatory, not cosmetic: Pi's own docs reuse the same key
+ * (`"my-ext"`) for both `statusKey` and `widgetKey` (rpc.md:1273,1289) because the natural pattern
+ * is an extension naming everything after itself. Un-namespaced, a status tick would silently
+ * delete that extension's own widget.
+ */
+function translateUiRequest(rec) {
+    const { type: _type, id, method, ...payload } = rec;
+    const methodName = method;
+    let surfaceKey;
+    let removed = false;
+    if (methodName === "setStatus") {
+        surfaceKey = `status:${rec.statusKey}`;
+        removed = rec.statusText === undefined;
+    }
+    else if (methodName === "setWidget") {
+        surfaceKey = `widget:${rec.widgetKey}`;
+        removed = rec.widgetLines === undefined;
+    }
+    else if (methodName === "setTitle") {
+        surfaceKey = "title";
+    }
+    return {
+        requestId: id,
+        method: methodName,
+        expectsResponse: DIALOG_METHODS.has(methodName),
+        payload,
+        ...(surfaceKey !== undefined ? { surfaceKey } : {}),
+        ...(removed ? { removed: true } : {}),
+        ...(typeof rec.timeout === "number" ? { timeoutMs: rec.timeout } : {}),
+    };
+}
 class PiAgentSession {
     transport;
     provider;
     id = randomUUID();
     capabilities = PI_CAPABILITIES;
     subscribers = new Set();
+    uiSubscribers = new Set();
     history = [];
     eventMapper = createPiEventMapper();
     modes = [];
@@ -59,17 +102,13 @@ class PiAgentSession {
         this.mode = opts.config.modeId ?? null;
         this.sessionFile = opts.sessionFile;
         transport.onEvent((raw) => {
-            // Auto-respond to extension UI dialogs so the agent never blocks waiting on a client that
-            // isn't wired for them (POC). Safe default: cancel (extension receives undefined/false).
             const rec = raw;
             if (rec?.type === "extension_ui_request") {
-                const method = rec.method;
-                if (method === "select" ||
-                    method === "confirm" ||
-                    method === "input" ||
-                    method === "editor") {
-                    this.transport.notify("extension_ui_response", { id: rec.id, cancelled: true });
-                }
+                // Forward to the daemon's UI channel — write no response here; the daemon answers, or
+                // nobody does (features/extension-ui-rpc.md § Behavior & algorithms).
+                const req = translateUiRequest(rec);
+                for (const cb of this.uiSubscribers)
+                    cb(req);
                 return;
             }
             const event = this.eventMapper.map(raw);
@@ -238,6 +277,15 @@ class PiAgentSession {
         this.transport.notify("respond_to_permission", { requestId, response });
         return Promise.resolve();
     }
+    onUiRequest(cb) {
+        this.uiSubscribers.add(cb);
+        return () => this.uiSubscribers.delete(cb);
+    }
+    /** Body spread first, `id` stamped last — a response containing an `id`/`type` key cannot
+     *  redirect which dialog it resolves (features/extension-ui-rpc.md § Public contract). */
+    respondToUi(providerRequestId, response) {
+        this.transport.notify("extension_ui_response", { ...response, id: providerRequestId });
+    }
     describePersistence() {
         return {
             provider: this.provider,

package/dist/daemon/bootstrap.js

@@ -25,6 +25,8 @@ import { createPasswordAuth, resolvePasswordHash } from "../auth/password-auth.j
 import { expandHome } from "../files/resolve-path.js";
 import { loadConfig } from "../config/daemon-config.js";
 import { createDaemonLogger } from "../logging/logger.js";
+import { registerAgentUiHandlers } from "../agent/agent-ui/agent-ui-rpc.js";
+import { AgentUiService } from "../agent/agent-ui/agent-ui-service.js";
 import { AgentManager } from "../agent/agent-manager.js";
 import { AgentService, getTimeline } from "../agent/agent-service.js";
 import { SessionOperationsService } from "../agent/session-operations.js";
@@ -177,12 +179,6 @@ export function startDaemon(opts) {
     });
     // ── Real provider resolution (pi spawns `pi --mode rpc`; mock is opt-in) ─────
     const resolveClient = (provider) => resolveProviderClient(provider, config, { logger });
-    // ── Disk-persisted agent manager (recovers agents on boot) ───────────────────
-    const manager = new AgentManager({
-        home,
-        saveAgent: (record) => saveAgent(home, record),
-        loadAllAgents: () => loadAllAgents(home),
-    });
     // ── Broadcast helper ─────────────────────────────────────────────────────────
     // See `wrapSessionEnvelope` above for the full rationale.
     const broadcast = (sessions, message) => {
@@ -200,13 +196,26 @@ export function startDaemon(opts) {
     const relayCapabilityStore = createInMemoryCapabilityStore();
     const sessionsHolder = { sessions: [] };
     const getActiveSessions = () => [...sessionsHolder.sessions, ...relaySessions];
+    // ── Extension UI bridge (features/extension-ui-rpc.md) — constructed before the manager so
+    // `onSessionAttached` below can close over it.
+    const agentUiService = new AgentUiService({ broadcast, getActiveSessions, logger });
+    // ── Disk-persisted agent manager (recovers agents on boot) ───────────────────
+    const manager = new AgentManager({
+        home,
+        saveAgent: (record) => saveAgent(home, record),
+        loadAllAgents: () => loadAllAgents(home),
+        onSessionAttached: (agentId, session) => agentUiService.attach(agentId, session),
+        logger,
+    });
     // Forward archive/delete lifecycle events to every connected client (multi-tab/multi-client
     // sync) — `agent_update` for status changes is already broadcast per-call-site; these two are
-    // manager-internal and only reach clients via this subscription.
+    // manager-internal and only reach clients via this subscription. Also sweeps the extension-UI
+    // bridge: every pending dialog and retained surface for the agent is cancelled/dropped.
     manager.subscribe((event) => {
         if (event.type === "agent_archived" || event.type === "agent_deleted") {
             logger.info({ agentId: event.agentId }, event.type.replace("_", " "));
             broadcast(getActiveSessions(), { type: "session", message: event });
+            agentUiService.sweep(event.agentId, "aborted");
         }
     });
     const registry = new HandlerRegistry(logger);
@@ -230,6 +239,7 @@ export function startDaemon(opts) {
     registerTimelineHandler(registry, { manager, resolveClient });
     const permissionService = new PermissionService({ manager, broadcast });
     permissionService.registerHandlers(registry, getActiveSessions);
+    registerAgentUiHandlers(registry, { service: agentUiService, logger });
     // ── Directory listing (agents) ────────────────────────────────────────────────
     registry.register("list_agents_request", (ctx) => ({
         type: "list_agents_response",
@@ -472,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/daemon/dev-bootstrap.d.ts

@@ -1,4 +1,5 @@
 import type { Server as HttpServer } from "node:http";
+import { AgentManager } from "../agent/agent-manager.js";
 import { type Logger } from "../logging/logger.js";
 export interface DevBootstrapOptions {
     host: string;
@@ -19,6 +20,11 @@ export interface DevBootstrapHandle {
     httpServer: HttpServer;
     serverId: string;
     logger: Logger;
+    /** Exposed for tests only (e.g. sprint-066/task-004's daemon-level extension-UI test): lets a
+     *  test reach a created agent's live `MockAgentSession` to script a UI dialog via
+     *  `emitUiRequest` — there is no WS RPC for that, by design (a real Pi process is what would
+     *  normally emit these). Not part of the RPC surface. */
+    manager: AgentManager;
     close(): Promise<void>;
 }
 export declare function startDevDaemon(opts: DevBootstrapOptions): DevBootstrapHandle;

package/dist/daemon/dev-bootstrap.js

@@ -13,6 +13,8 @@ import { expandHome } from "../files/resolve-path.js";
 import { createHttpServer } from "../http/http-server.js";
 import { createWebSocketServer } from "../ws/ws-server.js";
 import { HandlerRegistry, routeTextFrame } from "../ws/router.js";
+import { registerAgentUiHandlers } from "../agent/agent-ui/agent-ui-rpc.js";
+import { AgentUiService } from "../agent/agent-ui/agent-ui-service.js";
 import { AgentManager } from "../agent/agent-manager.js";
 import { AgentService } from "../agent/agent-service.js";
 import { SessionOperationsService } from "../agent/session-operations.js";
@@ -28,19 +30,6 @@ import { wrapSessionEnvelope } from "./bootstrap.js";
 export function startDevDaemon(opts) {
     const serverId = opts.serverId ?? randomUUID();
     const logger = opts.logger ?? createDaemonLogger(undefined);
-    // ── In-memory agent manager (no disk persistence in dev mode) ──────────────
-    const agentsById = new Map();
-    const manager = new AgentManager({
-        home: "/tmp/pi-studio-dev",
-        saveAgent: async (record) => {
-            agentsById.set(record.id, record);
-        },
-        loadAllAgents: async () => [...agentsById.values()],
-        deleteAgent: async (_cwd, id) => agentsById.delete(id),
-    });
-    // ── Provider resolution: mock only in dev ───────────────────────────────────
-    const mockClient = createMockClient({ turnDelayMs: opts.mockTurnDelayMs });
-    const resolveClient = (_provider) => mockClient;
     // ── Broadcast helper ─────────────────────────────────────────────────────────
     // See `bootstrap.ts`'s `wrapSessionEnvelope` for the full rationale.
     const broadcast = (sessions, message) => {
@@ -58,11 +47,34 @@ export function startDevDaemon(opts) {
     // mutable holder so they can be registered before the WS server exists.
     const sessionsHolder = { sessions: [] };
     const getActiveSessions = () => sessionsHolder.sessions;
+    // ── Extension UI bridge (features/extension-ui-rpc.md) — constructed before the manager so
+    // `onSessionAttached` below can close over it. Registered here (unlike production-only
+    // `provider_auth`/`file_watch`): the mock provider is this family's designated producer, and the
+    // dev daemon is mock-only, so a UI family unexercisable here would be untestable exactly where a
+    // sibling UI scope needs to develop against it.
+    const agentUiService = new AgentUiService({ broadcast, getActiveSessions, logger });
+    // ── In-memory agent manager (no disk persistence in dev mode) ──────────────
+    const agentsById = new Map();
+    const manager = new AgentManager({
+        home: "/tmp/pi-studio-dev",
+        saveAgent: async (record) => {
+            agentsById.set(record.id, record);
+        },
+        loadAllAgents: async () => [...agentsById.values()],
+        deleteAgent: async (_cwd, id) => agentsById.delete(id),
+        onSessionAttached: (agentId, session) => agentUiService.attach(agentId, session),
+        logger,
+    });
+    // ── Provider resolution: mock only in dev ───────────────────────────────────
+    const mockClient = createMockClient({ turnDelayMs: opts.mockTurnDelayMs });
+    const resolveClient = (_provider) => mockClient;
     // Forward archive/delete lifecycle events to every connected client (see bootstrap.ts's
-    // production twin for the full rationale).
+    // production twin for the full rationale). Also sweeps the extension-UI bridge: every pending
+    // dialog and retained surface for the agent is cancelled/dropped on archive or delete.
     manager.subscribe((event) => {
         if (event.type === "agent_archived" || event.type === "agent_deleted") {
             broadcast(getActiveSessions(), { type: "session", message: event });
+            agentUiService.sweep(event.agentId, "aborted");
         }
     });
     // ── Handler registry ────────────────────────────────────────────────────────
@@ -86,6 +98,7 @@ export function startDevDaemon(opts) {
     registerTimelineHandler(registry, { manager, resolveClient });
     const permissionService = new PermissionService({ manager, broadcast });
     permissionService.registerHandlers(registry, getActiveSessions);
+    registerAgentUiHandlers(registry, { service: agentUiService, logger });
     // ── list_agents_request: minimal directory listing (not in scope elsewhere) ─
     registry.register("list_agents_request", (ctx) => {
         const agents = manager.list().map((m) => ({
@@ -289,6 +302,7 @@ export function startDevDaemon(opts) {
         httpServer,
         serverId,
         logger,
+        manager,
         close: async () => {
             logger.info("dev daemon shutting down");
             await wsHandle.close();

package/dist/daemon/index.d.ts

@@ -13,4 +13,5 @@ export declare function createDaemonRuntimeInfo(input?: {
     mode?: "production" | "development";
 }): DaemonRuntimeInfo;
 export * from "./bootstrap.js";
+export * from "./dev-bootstrap.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/daemon/index.js

@@ -20,4 +20,8 @@ export function createDaemonRuntimeInfo(input = {}) {
 }
 // Production daemon bootstrap: startDaemon(), DaemonOptions, DaemonHandle, wrapSessionEnvelope().
 export * from "./bootstrap.js";
+// Dev daemon bootstrap (mock provider, in-memory): reachable from outside the package so
+// cross-package E2E (e.g. packages/cli's extension-UI SDK test, sprint-067/task-004) can host a
+// real dev daemon without a second, duplicated bootstrap.
+export * from "./dev-bootstrap.js";
 //# sourceMappingURL=index.js.map

package/dist/extensions/curated-packs.js

@@ -14,6 +14,9 @@ export const CURATED_PACKS = {
             { source: "npm:pi-web-access", addedIn: "0.0.73" },
             // Powerline-style status bar.
             { source: "npm:pi-powerline-footer", addedIn: "0.0.73" },
+            // Structured questionnaire tool: typed multiple-choice/free-text prompts instead of the
+            // model guessing when it lacks information it should ask for.
+            { source: "npm:@juicesharp/rpiv-ask-user-question", addedIn: "0.0.93" },
         ],
     },
 };

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