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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/session-host-core",
-  "version": "1.0.60-rc.7",
+  "version": "1.0.60-rc.71",
   "description": "ADHDev local session host core — session registry, protocol, buffers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/buffer.ts

@@ -75,10 +75,171 @@ export class SessionRingBuffer {
   }
 
   private trim(): void {
+    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.
+   */
+  private healHead(): void {
+    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;
+  }
+}
+
+/** Final byte of a CSI (`ESC [ … X`) or SS3 sequence. */
+const CSI_FINAL = /[\x40-\x7e]/;
+
+/**
+ * The subset of CSI final bytes terminals actually emit: cursor movement
+ * (ABCDEFGHfd), erase (JK), scroll (STLM), insert/delete (PX@), SGR (m),
+ * device status (nc), mode set/reset (hl), save/restore cursor (su) and
+ * scroll region (r). Used only when the `[` introducer was itself evicted, so
+ * that a digit run followed by an arbitrary letter is not mistaken for a
+ * sequence — the whole CSI final range \x40-\x7e includes most of the
+ * alphabet and would swallow ordinary prose.
+ */
+const CSI_COMMON_FINAL = /[ABCDEFGHJKSTLMPX@mnchlsurdfgqit]/;
+
+/**
+ * Returns `text` with any leading fragment of a torn character or escape
+ * sequence removed. Returns `text` unchanged when the head is already a safe
+ * place to start parsing.
+ */
+function stripDanglingPrefix(text: string): string {
+  let i = 0;
+
+  // 1. Encoding damage. A torn multi-byte sequence survives as U+FFFD or as an
+  //    unpaired surrogate; both are meaningless on their own.
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === 0xfffd) { i += 1; continue; }
+    // High surrogate followed by a low surrogate is a complete astral
+    // character — keep it. Either half alone is debris.
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) break;
+      i += 1;
+      continue;
+    }
+    if (code >= 0xdc00 && code <= 0xdfff) { i += 1; continue; }
+    break;
+  }
+
+  // 2. Escape-sequence damage. Only a *leading* fragment can be torn: anything
+  //    at or after the first ESC still has its introducer, so it will parse.
+  //    Scan to the first ESC (or to a control character that resynchronises the
+  //    parser anyway) and drop everything before it — but only if what precedes
+  //    it actually looks like the tail of a sequence rather than ordinary text,
+  //    so a buffer that legitimately starts mid-line is left alone.
+  const rest = text.slice(i);
+  const danglingLength = danglingEscapeTailLength(rest);
+  return danglingLength > 0 ? rest.slice(danglingLength) : rest;
+}
+
+/**
+ * Length of the leading run that is the tail of a cut escape sequence, or 0
+ * when the text starts cleanly.
+ *
+ * A cut CSI leaves one of:
+ *   `[2J…`  `2J…`  `J…`     (introducer and/or parameters lost)
+ * and a cut OSC leaves parameter/payload text terminated by BEL or ST. What
+ * they have in common is that the *remaining* prefix is a run of parameter
+ * bytes ending at a final byte, all of it before the next ESC. Ordinary output
+ * only matches that shape when it happens to consist solely of parameter
+ * characters, so the scan stops at the first character that cannot appear in a
+ * sequence — a letter mid-word, a space, a newline — and reports 0.
+ */
+function danglingEscapeTailLength(text: string): number {
+  if (!text || text.charCodeAt(0) === 0x1b) return 0;
+
+  let i = 0;
+  // An orphaned `[` is the most common shape (the ESC alone was evicted).
+  const hasIntroducer = text[0] === '[' || text[0] === ']';
+  if (hasIntroducer) i = 1;
+
+  const start = i;
+  // Parameter bytes only: digits, `;`, `?`, `:` and the private markers.
+  // Deliberately NOT the intermediate bytes (space, `!`, `"`, `$`, `'`):
+  // including space made ordinary prose match — "2 files changed" scans `2`,
+  // ` `, then treats `f` as a CSI final and eats "2 f". Sequences that use
+  // intermediates are rare enough that leaving their tail in place is far
+  // cheaper than truncating real output.
+  while (i < text.length && /[0-9;?:<=>]/.test(text[i])) i += 1;
+
+  if (i >= text.length) return 0;
+
+  // OSC tail: ends at BEL or ST rather than a CSI final byte.
+  if (text[0] === ']') {
+    const bel = text.indexOf('\x07');
+    if (bel >= 0) return bel + 1;
+    return 0;
+  }
+
+  if (!CSI_FINAL.test(text[i])) return 0;
+
+  // Require evidence of an actual sequence rather than a coincidence. With the
+  // orphaned `[` present the shape is already unambiguous. Without it, demand
+  // at least one parameter byte followed by one of the final bytes terminals
+  // actually emit — `32m` and `2J` are sequences; "J is a letter" has no
+  // parameter byte, and "2 files changed" ends its digit run at a space, which
+  // is not in the parameter class at all.
+  if (!hasIntroducer) {
+    if (i === start) return 0;
+    if (!CSI_COMMON_FINAL.test(text[i])) return 0;
+  }
+
+  return i + 1;
 }

package/src/control-plane.ts

@@ -1,6 +1,7 @@
 import type {
   AcquireWritePayload,
   GetHostDiagnosticsPayload,
+  GetSnapshotPayload,
   PruneDuplicateSessionsPayload,
   ReleaseWritePayload,
   SessionHostDiagnostics,
@@ -9,8 +10,17 @@ import type {
   SessionHostRequestType,
 } from './types.js';
 
+/** Response shape of the `get_snapshot` wire request — a PTY snapshot for a session. */
+export 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
@@ -28,6 +38,14 @@ export 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>;
 }
 
 /**
@@ -46,7 +64,7 @@ export interface SessionHostControlTransport {
 }
 
 /**
- * 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.
@@ -88,5 +106,8 @@ export function createSessionHostControlPlane(
     releaseWrite(payload: ReleaseWritePayload): Promise<SessionHostRecord | null> {
       return transport.request<SessionHostRecord | null>('release_write', payload as unknown as Record<string, unknown>);
     },
+    getSnapshot(sessionId: string, sinceSeq?: number): Promise<SessionHostSnapshot | null> {
+      return transport.request<SessionHostSnapshot | null>('get_snapshot', { sessionId, sinceSeq } as GetSnapshotPayload as unknown as Record<string, unknown>);
+    },
   };
 }

package/src/index.ts

@@ -102,4 +102,4 @@ export {
   ensureNodePtySpawnHelperPermissions,
 } from './spawn-env.js';
 export { createSessionHostControlPlane } from './control-plane.js';
-export type { SessionHostControlPlane, SessionHostControlTransport } from './control-plane.js';
+export type { SessionHostControlPlane, SessionHostControlTransport, SessionHostSnapshot } from './control-plane.js';

package/src/ipc.ts

@@ -83,8 +83,18 @@ function serializeEnvelope(envelope: SessionHostWireEnvelope): string {
  * 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.
  */
-function createLineParser(onEnvelope: (envelope: SessionHostWireEnvelope) => void) {
+function createLineParser<TEnvelope = SessionHostWireEnvelope>(
+  onEnvelope: (envelope: TEnvelope) => void,
+) {
   let buffer = '';
   const decoder = new StringDecoder('utf8');
   const parser = (chunk: Buffer | string) => {
@@ -94,7 +104,7 @@ function createLineParser(onEnvelope: (envelope: SessionHostWireEnvelope) => voi
       const rawLine = buffer.slice(0, newlineIndex).trim();
       buffer = buffer.slice(newlineIndex + 1);
       if (rawLine) {
-        onEnvelope(JSON.parse(rawLine) as SessionHostWireEnvelope);
+        onEnvelope(JSON.parse(rawLine) as TEnvelope);
       }
       newlineIndex = buffer.indexOf('\n');
     }

package/src/registry.ts

@@ -274,7 +274,20 @@ export class SessionHostRegistry {
       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: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!meta) return {};
+  try {
+    return structuredClone(meta);
+  } catch {
+    // A non-cloneable value (function, class instance) — keep the old shallow copy.
+    return { ...meta };
+  }
+}