@adhdev/session-host-core 1.0.60-rc.7 → 1.0.60-rc.70

package/dist/index.d.mts

@@ -456,6 +456,47 @@ declare class SessionRingBuffer {
         text: string;
     }): void;
     private trim;
+    /**
+     * TRIM-BOUNDARY repair. Eviction drops whole chunks, and a chunk boundary is
+     * a PTY read boundary — an arbitrary byte offset with no relationship to the
+     * structure of the stream. So the chunk that becomes the new oldest can begin
+     * partway through something the sender wrote atomically, and `snapshot()`
+     * joins from exactly there.
+     *
+     * The consumer is the browser terminal: "Load older terminal output" asks
+     * with `sinceSeq: 0`, which makes the daemon skip the emulator viewport and
+     * hand this raw text straight to xterm (see `mergeRuntimeSnapshot`). xterm
+     * then parses a stream that starts mid-token, which is how the reported
+     * screenshot got orphaned `.` and `5` glyphs floating above the output and a
+     * large blank band at the top:
+     *
+     *   drop 5 chars  -> "[HClaude Code v2.1.220…"   the CSI introducer is gone,
+     *                                                so `[H` prints literally
+     *   drop 12 chars -> "2mClaude Code v2.1.220…"   half an SGR prints literally
+     *   drop 46 chars -> the leading `\x1b[2J\x1b[H` never arrives, so the screen
+     *                    is never cleared/homed and row placement collapses
+     *   byte cut      -> a torn 3-byte Hangul sequence decodes to U+FFFD
+     *
+     * So walk the head of the new oldest chunk forward to the first offset that
+     * is safe to start parsing at, and drop the partial prefix. Losing a few
+     * bytes of already-evicted context is strictly better than injecting literal
+     * garbage into the viewport.
+     *
+     * Two independent boundary classes have to be handled, and neither subsumes
+     * the other:
+     *
+     *  1. Character encoding. Chunks are JS strings, so a torn multi-byte UTF-8
+     *     sequence has already decayed into U+FFFD (or, for astral characters, a
+     *     lone surrogate) by the time it gets here. This mirrors the protection
+     *     `createLineParser` grew for the IPC socket path in
+     *     `ipc-line-parser-utf8.test.ts`; that layer can hold bytes back and
+     *     re-join them because it owns both sides of the split, whereas here the
+     *     other half is already gone, so dropping is the only repair available.
+     *  2. Escape sequences. A CSI/OSC/SS3 can be cut anywhere, and unlike the
+     *     encoding case the leftover bytes are all perfectly printable — which is
+     *     precisely why the corruption is visible rather than silent.
+     */
+    private healHead;
 }
 
 declare class SessionHostRegistry {
@@ -549,8 +590,16 @@ declare function getDefaultSessionHostEndpoint(appName?: string, options?: Sessi
  * finish it arrive, which is the only correct way to turn a byte stream into
  * text. String chunks bypass it: they are already decoded, and feeding them
  * through `Buffer.from` would re-encode text the caller never asked us to touch.
+ *
+ * The envelope type is a parameter (defaulting to this package's own wire type)
+ * purely so sibling newline-framed sockets can REUSE this decoder rather than
+ * re-deriving it. `@adhdev/terminal-mux-control`'s control socket carried a
+ * verbatim `chunk.toString()` copy of the pre-fix parser and inherited the same
+ * silent corruption; it now shares this implementation. Nothing about the
+ * framing is session-host-specific — only the payload type was, and that is now
+ * the caller's to name.
  */
-declare function createLineParser(onEnvelope: (envelope: SessionHostWireEnvelope) => void): {
+declare function createLineParser<TEnvelope = SessionHostWireEnvelope>(onEnvelope: (envelope: TEnvelope) => void): {
     (chunk: Buffer | string): void;
     end(): string;
 };
@@ -700,8 +749,16 @@ declare function applyTerminalColorEnv(env: Record<string, string>): void;
  */
 declare function ensureNodePtySpawnHelperPermissions(logFn?: (msg: string) => void): void;
 
+/** Response shape of the `get_snapshot` wire request — a PTY snapshot for a session. */
+interface SessionHostSnapshot {
+    seq: number;
+    text: string;
+    truncated: boolean;
+    cols?: number;
+    rows?: number;
+}
 /**
- * The 11-method session-host control-plane surface shared by the cloud and
+ * The session-host control-plane surface shared by the cloud and
  * standalone daemons. Both daemons used to carry a byte-for-byte copy of this
  * dispatch table plus the identical throw strings; this is the single source of
  * truth for that mapping. The wire `type` strings and error text here are the
@@ -721,6 +778,14 @@ interface SessionHostControlPlane {
     pruneDuplicateSessions(payload?: PruneDuplicateSessionsPayload): Promise<SessionHostPruneDuplicatesResult>;
     acquireWrite(payload: AcquireWritePayload): Promise<SessionHostRecord | null>;
     releaseWrite(payload: ReleaseWritePayload): Promise<SessionHostRecord | null>;
+    /**
+     * A PTY snapshot for `sessionId` (optionally only the tail since `sinceSeq`),
+     * over wire type `get_snapshot`. Mirrors the shape daemon-core's local
+     * `SessionHostControlPlane` interface (`commands/router.ts`) and cloud's
+     * former `cloud-command-transports.ts` P2P-only `get_runtime_snapshot` case
+     * both already used against a raw `SessionHostClient`.
+     */
+    getSnapshot(sessionId: string, sinceSeq?: number): Promise<SessionHostSnapshot | null>;
 }
 /**
  * Minimal request transport the control-plane factory needs. Each daemon injects
@@ -737,11 +802,11 @@ interface SessionHostControlTransport {
     request<T>(type: SessionHostRequestType, payload: Record<string, unknown>): Promise<T>;
 }
 /**
- * Build the shared 11-method control-plane over an injected request transport.
+ * Build the shared 12-method control-plane over an injected request transport.
  * The (type string, payload shape) pairs are verbatim what both daemons emitted
  * previously — do not reword them without matching the session-host daemon's
  * request handlers.
  */
 declare function createSessionHostControlPlane(transport: SessionHostControlTransport): SessionHostControlPlane;
 
-export { type AcquireWritePayload, type AttachSessionPayload, type ClearSessionBufferPayload, type CreateSessionPayload, DEFAULT_CONFIG_DIR_NAME, DEFAULT_SESSION_RING_BUFFER_MAX_BYTES, type DetachSessionPayload, type ForceDetachClientPayload, type GetHostDiagnosticsPayload, type GetSnapshotPayload, type GetTerminalSnapshotPayload, type PruneDuplicateSessionsPayload, type ReleaseWritePayload, type ResizeSessionPayload, type RestartSessionPayload, type ResumeSessionPayload, SESSION_HOST_SUPPORTED_REQUEST_TYPES, type SendInputPayload, type SendSignalPayload, type SessionAttachedClient, type SessionBufferSnapshot, type SessionClientType, type SessionHostCategory, SessionHostClient, type SessionHostClientOptions, type SessionHostControlPlane, type SessionHostControlTransport, type SessionHostDiagnostics, type SessionHostDisconnectInfo, type SessionHostDisconnectReason, type SessionHostDuplicateSessionGroup, type SessionHostEndpoint, type SessionHostEndpointOptions, type SessionHostEvent, type SessionHostEventEnvelope, type SessionHostLogEntry, type SessionHostPruneDuplicatesResult, type SessionHostRecord, SessionHostRegistry, type SessionHostRequest, type SessionHostRequestEnvelope, type SessionHostRequestTrace, type SessionHostRequestType, type SessionHostResponse, type SessionHostResponseEnvelope, type SessionHostRuntimeTransition, type SessionHostSurfaceKind, type SessionHostSurfaceRecordLike, type SessionHostWireEnvelope, type SessionLaunchCommand, type SessionLifecycle, type SessionOwnerType, SessionRingBuffer, type SessionRingBufferOptions, type SessionTerminalSnapshot, type SessionTerminalState, type SessionTermination, type SessionTransport, type SessionWriteOwner, type StopSessionPayload, type UpdateSessionMetaPayload, applyTerminalColorEnv, buildRuntimeDisplayName, buildRuntimeKey, canonicalizeInstancePath, classifyTermination, createLineParser, createResponseEnvelope, createSessionHostControlPlane, ensureNodePtySpawnHelperPermissions, formatRuntimeOwner, getDefaultSessionHostEndpoint, getSessionHostRecoveryLabel, getSessionHostSurfaceKind, getWorkspaceLabel, isDefaultInstanceConfigDir, isSessionHostLiveRuntime, isSessionHostRecoverySnapshot, isTerminalRecord, partitionSessionHostDiagnosticsSessions, partitionSessionHostRecords, resolveAttachableRuntimeRecord, resolveInstanceConfigDir, resolveRuntimeRecord, resolveSessionHostIpcKey, sanitizeSpawnEnv, writeEnvelope };
+export { type AcquireWritePayload, type AttachSessionPayload, type ClearSessionBufferPayload, type CreateSessionPayload, DEFAULT_CONFIG_DIR_NAME, DEFAULT_SESSION_RING_BUFFER_MAX_BYTES, type DetachSessionPayload, type ForceDetachClientPayload, type GetHostDiagnosticsPayload, type GetSnapshotPayload, type GetTerminalSnapshotPayload, type PruneDuplicateSessionsPayload, type ReleaseWritePayload, type ResizeSessionPayload, type RestartSessionPayload, type ResumeSessionPayload, SESSION_HOST_SUPPORTED_REQUEST_TYPES, type SendInputPayload, type SendSignalPayload, type SessionAttachedClient, type SessionBufferSnapshot, type SessionClientType, type SessionHostCategory, SessionHostClient, type SessionHostClientOptions, type SessionHostControlPlane, type SessionHostControlTransport, type SessionHostDiagnostics, type SessionHostDisconnectInfo, type SessionHostDisconnectReason, type SessionHostDuplicateSessionGroup, type SessionHostEndpoint, type SessionHostEndpointOptions, type SessionHostEvent, type SessionHostEventEnvelope, type SessionHostLogEntry, type SessionHostPruneDuplicatesResult, type SessionHostRecord, SessionHostRegistry, type SessionHostRequest, type SessionHostRequestEnvelope, type SessionHostRequestTrace, type SessionHostRequestType, type SessionHostResponse, type SessionHostResponseEnvelope, type SessionHostRuntimeTransition, type SessionHostSnapshot, type SessionHostSurfaceKind, type SessionHostSurfaceRecordLike, type SessionHostWireEnvelope, type SessionLaunchCommand, type SessionLifecycle, type SessionOwnerType, SessionRingBuffer, type SessionRingBufferOptions, type SessionTerminalSnapshot, type SessionTerminalState, type SessionTermination, type SessionTransport, type SessionWriteOwner, type StopSessionPayload, type UpdateSessionMetaPayload, applyTerminalColorEnv, buildRuntimeDisplayName, buildRuntimeKey, canonicalizeInstancePath, classifyTermination, createLineParser, createResponseEnvelope, createSessionHostControlPlane, ensureNodePtySpawnHelperPermissions, formatRuntimeOwner, getDefaultSessionHostEndpoint, getSessionHostRecoveryLabel, getSessionHostSurfaceKind, getWorkspaceLabel, isDefaultInstanceConfigDir, isSessionHostLiveRuntime, isSessionHostRecoverySnapshot, isTerminalRecord, partitionSessionHostDiagnosticsSessions, partitionSessionHostRecords, resolveAttachableRuntimeRecord, resolveInstanceConfigDir, resolveRuntimeRecord, resolveSessionHostIpcKey, sanitizeSpawnEnv, writeEnvelope };

package/dist/index.d.ts

@@ -456,6 +456,47 @@ declare class SessionRingBuffer {
         text: string;
     }): void;
     private trim;
+    /**
+     * TRIM-BOUNDARY repair. Eviction drops whole chunks, and a chunk boundary is
+     * a PTY read boundary — an arbitrary byte offset with no relationship to the
+     * structure of the stream. So the chunk that becomes the new oldest can begin
+     * partway through something the sender wrote atomically, and `snapshot()`
+     * joins from exactly there.
+     *
+     * The consumer is the browser terminal: "Load older terminal output" asks
+     * with `sinceSeq: 0`, which makes the daemon skip the emulator viewport and
+     * hand this raw text straight to xterm (see `mergeRuntimeSnapshot`). xterm
+     * then parses a stream that starts mid-token, which is how the reported
+     * screenshot got orphaned `.` and `5` glyphs floating above the output and a
+     * large blank band at the top:
+     *
+     *   drop 5 chars  -> "[HClaude Code v2.1.220…"   the CSI introducer is gone,
+     *                                                so `[H` prints literally
+     *   drop 12 chars -> "2mClaude Code v2.1.220…"   half an SGR prints literally
+     *   drop 46 chars -> the leading `\x1b[2J\x1b[H` never arrives, so the screen
+     *                    is never cleared/homed and row placement collapses
+     *   byte cut      -> a torn 3-byte Hangul sequence decodes to U+FFFD
+     *
+     * So walk the head of the new oldest chunk forward to the first offset that
+     * is safe to start parsing at, and drop the partial prefix. Losing a few
+     * bytes of already-evicted context is strictly better than injecting literal
+     * garbage into the viewport.
+     *
+     * Two independent boundary classes have to be handled, and neither subsumes
+     * the other:
+     *
+     *  1. Character encoding. Chunks are JS strings, so a torn multi-byte UTF-8
+     *     sequence has already decayed into U+FFFD (or, for astral characters, a
+     *     lone surrogate) by the time it gets here. This mirrors the protection
+     *     `createLineParser` grew for the IPC socket path in
+     *     `ipc-line-parser-utf8.test.ts`; that layer can hold bytes back and
+     *     re-join them because it owns both sides of the split, whereas here the
+     *     other half is already gone, so dropping is the only repair available.
+     *  2. Escape sequences. A CSI/OSC/SS3 can be cut anywhere, and unlike the
+     *     encoding case the leftover bytes are all perfectly printable — which is
+     *     precisely why the corruption is visible rather than silent.
+     */
+    private healHead;
 }
 
 declare class SessionHostRegistry {
@@ -549,8 +590,16 @@ declare function getDefaultSessionHostEndpoint(appName?: string, options?: Sessi
  * finish it arrive, which is the only correct way to turn a byte stream into
  * text. String chunks bypass it: they are already decoded, and feeding them
  * through `Buffer.from` would re-encode text the caller never asked us to touch.
+ *
+ * The envelope type is a parameter (defaulting to this package's own wire type)
+ * purely so sibling newline-framed sockets can REUSE this decoder rather than
+ * re-deriving it. `@adhdev/terminal-mux-control`'s control socket carried a
+ * verbatim `chunk.toString()` copy of the pre-fix parser and inherited the same
+ * silent corruption; it now shares this implementation. Nothing about the
+ * framing is session-host-specific — only the payload type was, and that is now
+ * the caller's to name.
  */
-declare function createLineParser(onEnvelope: (envelope: SessionHostWireEnvelope) => void): {
+declare function createLineParser<TEnvelope = SessionHostWireEnvelope>(onEnvelope: (envelope: TEnvelope) => void): {
     (chunk: Buffer | string): void;
     end(): string;
 };
@@ -700,8 +749,16 @@ declare function applyTerminalColorEnv(env: Record<string, string>): void;
  */
 declare function ensureNodePtySpawnHelperPermissions(logFn?: (msg: string) => void): void;
 
+/** Response shape of the `get_snapshot` wire request — a PTY snapshot for a session. */
+interface SessionHostSnapshot {
+    seq: number;
+    text: string;
+    truncated: boolean;
+    cols?: number;
+    rows?: number;
+}
 /**
- * The 11-method session-host control-plane surface shared by the cloud and
+ * The session-host control-plane surface shared by the cloud and
  * standalone daemons. Both daemons used to carry a byte-for-byte copy of this
  * dispatch table plus the identical throw strings; this is the single source of
  * truth for that mapping. The wire `type` strings and error text here are the
@@ -721,6 +778,14 @@ interface SessionHostControlPlane {
     pruneDuplicateSessions(payload?: PruneDuplicateSessionsPayload): Promise<SessionHostPruneDuplicatesResult>;
     acquireWrite(payload: AcquireWritePayload): Promise<SessionHostRecord | null>;
     releaseWrite(payload: ReleaseWritePayload): Promise<SessionHostRecord | null>;
+    /**
+     * A PTY snapshot for `sessionId` (optionally only the tail since `sinceSeq`),
+     * over wire type `get_snapshot`. Mirrors the shape daemon-core's local
+     * `SessionHostControlPlane` interface (`commands/router.ts`) and cloud's
+     * former `cloud-command-transports.ts` P2P-only `get_runtime_snapshot` case
+     * both already used against a raw `SessionHostClient`.
+     */
+    getSnapshot(sessionId: string, sinceSeq?: number): Promise<SessionHostSnapshot | null>;
 }
 /**
  * Minimal request transport the control-plane factory needs. Each daemon injects
@@ -737,11 +802,11 @@ interface SessionHostControlTransport {
     request<T>(type: SessionHostRequestType, payload: Record<string, unknown>): Promise<T>;
 }
 /**
- * Build the shared 11-method control-plane over an injected request transport.
+ * Build the shared 12-method control-plane over an injected request transport.
  * The (type string, payload shape) pairs are verbatim what both daemons emitted
  * previously — do not reword them without matching the session-host daemon's
  * request handlers.
  */
 declare function createSessionHostControlPlane(transport: SessionHostControlTransport): SessionHostControlPlane;
 
-export { type AcquireWritePayload, type AttachSessionPayload, type ClearSessionBufferPayload, type CreateSessionPayload, DEFAULT_CONFIG_DIR_NAME, DEFAULT_SESSION_RING_BUFFER_MAX_BYTES, type DetachSessionPayload, type ForceDetachClientPayload, type GetHostDiagnosticsPayload, type GetSnapshotPayload, type GetTerminalSnapshotPayload, type PruneDuplicateSessionsPayload, type ReleaseWritePayload, type ResizeSessionPayload, type RestartSessionPayload, type ResumeSessionPayload, SESSION_HOST_SUPPORTED_REQUEST_TYPES, type SendInputPayload, type SendSignalPayload, type SessionAttachedClient, type SessionBufferSnapshot, type SessionClientType, type SessionHostCategory, SessionHostClient, type SessionHostClientOptions, type SessionHostControlPlane, type SessionHostControlTransport, type SessionHostDiagnostics, type SessionHostDisconnectInfo, type SessionHostDisconnectReason, type SessionHostDuplicateSessionGroup, type SessionHostEndpoint, type SessionHostEndpointOptions, type SessionHostEvent, type SessionHostEventEnvelope, type SessionHostLogEntry, type SessionHostPruneDuplicatesResult, type SessionHostRecord, SessionHostRegistry, type SessionHostRequest, type SessionHostRequestEnvelope, type SessionHostRequestTrace, type SessionHostRequestType, type SessionHostResponse, type SessionHostResponseEnvelope, type SessionHostRuntimeTransition, type SessionHostSurfaceKind, type SessionHostSurfaceRecordLike, type SessionHostWireEnvelope, type SessionLaunchCommand, type SessionLifecycle, type SessionOwnerType, SessionRingBuffer, type SessionRingBufferOptions, type SessionTerminalSnapshot, type SessionTerminalState, type SessionTermination, type SessionTransport, type SessionWriteOwner, type StopSessionPayload, type UpdateSessionMetaPayload, applyTerminalColorEnv, buildRuntimeDisplayName, buildRuntimeKey, canonicalizeInstancePath, classifyTermination, createLineParser, createResponseEnvelope, createSessionHostControlPlane, ensureNodePtySpawnHelperPermissions, formatRuntimeOwner, getDefaultSessionHostEndpoint, getSessionHostRecoveryLabel, getSessionHostSurfaceKind, getWorkspaceLabel, isDefaultInstanceConfigDir, isSessionHostLiveRuntime, isSessionHostRecoverySnapshot, isTerminalRecord, partitionSessionHostDiagnosticsSessions, partitionSessionHostRecords, resolveAttachableRuntimeRecord, resolveInstanceConfigDir, resolveRuntimeRecord, resolveSessionHostIpcKey, sanitizeSpawnEnv, writeEnvelope };
+export { type AcquireWritePayload, type AttachSessionPayload, type ClearSessionBufferPayload, type CreateSessionPayload, DEFAULT_CONFIG_DIR_NAME, DEFAULT_SESSION_RING_BUFFER_MAX_BYTES, type DetachSessionPayload, type ForceDetachClientPayload, type GetHostDiagnosticsPayload, type GetSnapshotPayload, type GetTerminalSnapshotPayload, type PruneDuplicateSessionsPayload, type ReleaseWritePayload, type ResizeSessionPayload, type RestartSessionPayload, type ResumeSessionPayload, SESSION_HOST_SUPPORTED_REQUEST_TYPES, type SendInputPayload, type SendSignalPayload, type SessionAttachedClient, type SessionBufferSnapshot, type SessionClientType, type SessionHostCategory, SessionHostClient, type SessionHostClientOptions, type SessionHostControlPlane, type SessionHostControlTransport, type SessionHostDiagnostics, type SessionHostDisconnectInfo, type SessionHostDisconnectReason, type SessionHostDuplicateSessionGroup, type SessionHostEndpoint, type SessionHostEndpointOptions, type SessionHostEvent, type SessionHostEventEnvelope, type SessionHostLogEntry, type SessionHostPruneDuplicatesResult, type SessionHostRecord, SessionHostRegistry, type SessionHostRequest, type SessionHostRequestEnvelope, type SessionHostRequestTrace, type SessionHostRequestType, type SessionHostResponse, type SessionHostResponseEnvelope, type SessionHostRuntimeTransition, type SessionHostSnapshot, type SessionHostSurfaceKind, type SessionHostSurfaceRecordLike, type SessionHostWireEnvelope, type SessionLaunchCommand, type SessionLifecycle, type SessionOwnerType, SessionRingBuffer, type SessionRingBufferOptions, type SessionTerminalSnapshot, type SessionTerminalState, type SessionTermination, type SessionTransport, type SessionWriteOwner, type StopSessionPayload, type UpdateSessionMetaPayload, applyTerminalColorEnv, buildRuntimeDisplayName, buildRuntimeKey, canonicalizeInstancePath, classifyTermination, createLineParser, createResponseEnvelope, createSessionHostControlPlane, ensureNodePtySpawnHelperPermissions, formatRuntimeOwner, getDefaultSessionHostEndpoint, getSessionHostRecoveryLabel, getSessionHostSurfaceKind, getWorkspaceLabel, isDefaultInstanceConfigDir, isSessionHostLiveRuntime, isSessionHostRecoverySnapshot, isTerminalRecord, partitionSessionHostDiagnosticsSessions, partitionSessionHostRecords, resolveAttachableRuntimeRecord, resolveInstanceConfigDir, resolveRuntimeRecord, resolveSessionHostIpcKey, sanitizeSpawnEnv, writeEnvelope };

package/dist/index.js

@@ -181,13 +181,112 @@ var SessionRingBuffer = class {
     this.trim();
   }
   trim() {
+    let evicted = false;
     while (this.totalBytes > this.maxBytes && this.chunks.length > 1) {
       const removed = this.chunks.shift();
       if (!removed) break;
       this.totalBytes -= removed.bytes;
+      evicted = true;
     }
+    if (evicted) this.healHead();
+  }
+  /**
+   * TRIM-BOUNDARY repair. Eviction drops whole chunks, and a chunk boundary is
+   * a PTY read boundary — an arbitrary byte offset with no relationship to the
+   * structure of the stream. So the chunk that becomes the new oldest can begin
+   * partway through something the sender wrote atomically, and `snapshot()`
+   * joins from exactly there.
+   *
+   * The consumer is the browser terminal: "Load older terminal output" asks
+   * with `sinceSeq: 0`, which makes the daemon skip the emulator viewport and
+   * hand this raw text straight to xterm (see `mergeRuntimeSnapshot`). xterm
+   * then parses a stream that starts mid-token, which is how the reported
+   * screenshot got orphaned `.` and `5` glyphs floating above the output and a
+   * large blank band at the top:
+   *
+   *   drop 5 chars  -> "[HClaude Code v2.1.220…"   the CSI introducer is gone,
+   *                                                so `[H` prints literally
+   *   drop 12 chars -> "2mClaude Code v2.1.220…"   half an SGR prints literally
+   *   drop 46 chars -> the leading `\x1b[2J\x1b[H` never arrives, so the screen
+   *                    is never cleared/homed and row placement collapses
+   *   byte cut      -> a torn 3-byte Hangul sequence decodes to U+FFFD
+   *
+   * So walk the head of the new oldest chunk forward to the first offset that
+   * is safe to start parsing at, and drop the partial prefix. Losing a few
+   * bytes of already-evicted context is strictly better than injecting literal
+   * garbage into the viewport.
+   *
+   * Two independent boundary classes have to be handled, and neither subsumes
+   * the other:
+   *
+   *  1. Character encoding. Chunks are JS strings, so a torn multi-byte UTF-8
+   *     sequence has already decayed into U+FFFD (or, for astral characters, a
+   *     lone surrogate) by the time it gets here. This mirrors the protection
+   *     `createLineParser` grew for the IPC socket path in
+   *     `ipc-line-parser-utf8.test.ts`; that layer can hold bytes back and
+   *     re-join them because it owns both sides of the split, whereas here the
+   *     other half is already gone, so dropping is the only repair available.
+   *  2. Escape sequences. A CSI/OSC/SS3 can be cut anywhere, and unlike the
+   *     encoding case the leftover bytes are all perfectly printable — which is
+   *     precisely why the corruption is visible rather than silent.
+   */
+  healHead() {
+    const head = this.chunks[0];
+    if (!head) return;
+    const repaired = stripDanglingPrefix(head.data);
+    if (repaired === head.data) return;
+    const bytes = Buffer.byteLength(repaired, "utf8");
+    this.totalBytes -= head.bytes - bytes;
+    head.data = repaired;
+    head.bytes = bytes;
   }
 };
+var CSI_FINAL = /[\x40-\x7e]/;
+var CSI_COMMON_FINAL = /[ABCDEFGHJKSTLMPX@mnchlsurdfgqit]/;
+function stripDanglingPrefix(text) {
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === 65533) {
+      i += 1;
+      continue;
+    }
+    if (code >= 55296 && code <= 56319) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) break;
+      i += 1;
+      continue;
+    }
+    if (code >= 56320 && code <= 57343) {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  const rest = text.slice(i);
+  const danglingLength = danglingEscapeTailLength(rest);
+  return danglingLength > 0 ? rest.slice(danglingLength) : rest;
+}
+function danglingEscapeTailLength(text) {
+  if (!text || text.charCodeAt(0) === 27) return 0;
+  let i = 0;
+  const hasIntroducer = text[0] === "[" || text[0] === "]";
+  if (hasIntroducer) i = 1;
+  const start = i;
+  while (i < text.length && /[0-9;?:<=>]/.test(text[i])) i += 1;
+  if (i >= text.length) return 0;
+  if (text[0] === "]") {
+    const bel = text.indexOf("\x07");
+    if (bel >= 0) return bel + 1;
+    return 0;
+  }
+  if (!CSI_FINAL.test(text[i])) return 0;
+  if (!hasIntroducer) {
+    if (i === start) return 0;
+    if (!CSI_COMMON_FINAL.test(text[i])) return 0;
+  }
+  return i + 1;
+}
 
 // src/defaults.ts
 var DEFAULT_SESSION_HOST_COLS = 80;
@@ -571,10 +670,21 @@ var SessionHostRegistry = class {
       writeOwner: record.writeOwner ? { ...record.writeOwner } : null,
       attachedClients: record.attachedClients.map((client) => ({ ...client })),
       buffer: { ...record.buffer },
-      meta: { ...record.meta }
+      // Deep: meta carries nested records (e.g. the daemon's `launchRecord`,
+      // wiring-unification Phase E), and a caller mutating a returned record
+      // must never reach into the registry's own copy.
+      meta: cloneMeta(record.meta)
     };
   }
 };
+function cloneMeta(meta) {
+  if (!meta) return {};
+  try {
+    return structuredClone(meta);
+  } catch {
+    return { ...meta };
+  }
+}
 
 // src/ipc.ts
 var os = __toESM(require("os"));
@@ -960,6 +1070,9 @@ function createSessionHostControlPlane(transport) {
     },
     releaseWrite(payload) {
       return transport.request("release_write", payload);
+    },
+    getSnapshot(sessionId, sinceSeq) {
+      return transport.request("get_snapshot", { sessionId, sinceSeq });
     }
   };
 }