@fitchmultz/pi-subagents 0.46.1 → 0.46.2

package/src/history/ingest.ts

@@ -9,7 +9,7 @@ import { AnswerTexts } from "./answer-texts.ts";
 import { object } from "./values.ts";
 import { identity, stamp, openSource, requireSource } from "./source-file.ts";
 export { identity, stamp } from "./source-file.ts";
-import { number, text } from "./rows.ts";
+import { number, text, type Row } from "./rows.ts";
 import { stageEntry, publishTools, type IngestRecord } from "./entry-ingestion.ts";
 export { previewProjection, previewLimits, compactEntry } from "./preview.ts";
 
@@ -173,7 +173,6 @@ export class SourceIngest {
       });
       return;
     }
-    this.stagedEntry = stageEntry(this.store, this.source, record);
     this.textCursor = 0;
     this.phase = "text";
   }
@@ -235,64 +234,73 @@ export class SourceIngest {
   }
   private indexText(): void {
     const record = this.record;
-    const rowid = this.stagedEntry;
-    if (!record || rowid === undefined) {
-      throw new HistoryIndexError("CORRUPT", "Missing staged entry.");
+    if (!record) {
+      throw new HistoryIndexError("CORRUPT", "Missing ingestion record.");
     }
     const chunks = this.store.all(
-      "SELECT rowid,* FROM pending_text WHERE rowid>? ORDER BY rowid LIMIT 32",
+      "SELECT rowid,* FROM pending_text WHERE rowid>? ORDER BY rowid LIMIT 33",
       this.textCursor,
     );
-    if (chunks.length > 0) {
-      this.store.transaction(() => {
-        for (const chunk of chunks) {
-          if (!allowed(record.value, text(chunk, "field"))) {
-            continue;
-          }
-          const body = safeText(text(chunk, "text"), 1_048_576);
-          const id = this.store.run(
-            "INSERT INTO documents(entry_rowid,field,text_start,text_end,preview) VALUES (?,?,?,?,?)",
-            rowid,
-            text(chunk, "field"),
-            number(chunk, "position"),
-            number(chunk, "end_position"),
-            safeText(body, 512),
-          ).lastInsertRowid;
-          this.store.run("INSERT INTO corpus(rowid,text) VALUES (?,?)", id, body);
-        }
-      });
-      const last = chunks.at(-1);
-      if (last) {
-        this.textCursor = number(last, "rowid");
+    const complete = chunks.length <= 32;
+    const batch = chunks.slice(0, 32);
+    let rowid: number | undefined;
+    const write = () => {
+      rowid = this.stagedEntry ?? stageEntry(this.store, this.source, record);
+      this.indexChunks(rowid, record, batch);
+      if (complete) {
+        this.publishEntry(rowid, record);
       }
-      return;
+    };
+    if (complete) {
+      this.published(record.end, write);
+      this.stagedEntry = undefined;
+      this.phase = "read";
+    } else {
+      this.store.transaction(write);
+      this.stagedEntry = rowid;
+      this.textCursor = number(batch[31], "rowid");
     }
+  }
+  private indexChunks(rowid: number, record: IngestRecord, chunks: readonly Row[]): void {
+    for (const chunk of chunks) {
+      if (!allowed(record.value, text(chunk, "field"))) {
+        continue;
+      }
+      const body = safeText(text(chunk, "text"), 1_048_576);
+      const id = this.store.run(
+        "INSERT INTO documents(entry_rowid,field,text_start,text_end,preview) VALUES (?,?,?,?,?)",
+        rowid,
+        text(chunk, "field"),
+        number(chunk, "position"),
+        number(chunk, "end_position"),
+        safeText(body, 512),
+      ).lastInsertRowid;
+      this.store.run("INSERT INTO corpus(rowid,text) VALUES (?,?)", id, body);
+    }
+  }
+  private publishEntry(rowid: number, record: IngestRecord): void {
     const value = record.value;
     const answers = this.answerTexts.fingerprints(
       value,
       typeof value.id === "string" ? value.id : `legacy-${record.start}`,
     );
-    this.published(record.end, () => {
-      if (
-        this.store.run(
-          "UPDATE entries SET published=1 WHERE rowid=? AND source_id=? AND generation=? AND published=0",
-          rowid,
-          this.id,
-          this.source.generation,
-        ).changes !== 1
-      ) {
-        throw new HistoryIndexError(
-          "SOURCE_CHANGED",
-          "Staged entry disappeared before publication; reconcile before advancing the source.",
-        );
-      }
-      for (const [digest, item] of answers) {
-        this.store.run("INSERT OR IGNORE INTO answers VALUES (?,?,?)", rowid, digest, item);
-      }
-      publishTools(this.store, this.source, rowid, value);
-    });
-    this.stagedEntry = undefined;
-    this.phase = "read";
+    if (
+      this.store.run(
+        "UPDATE entries SET published=1 WHERE rowid=? AND source_id=? AND generation=? AND published=0",
+        rowid,
+        this.id,
+        this.source.generation,
+      ).changes !== 1
+    ) {
+      throw new HistoryIndexError(
+        "SOURCE_CHANGED",
+        "Staged entry disappeared before publication; reconcile before advancing the source.",
+      );
+    }
+    for (const [digest, item] of answers) {
+      this.store.run("INSERT OR IGNORE INTO answers VALUES (?,?,?)", rowid, digest, item);
+    }
+    publishTools(this.store, this.source, rowid, value);
   }
   /** Each pump reads <=64 KiB or indexes <=32 chunks, then returns to the IPC event loop. */
   step(): boolean {

package/src/history/prune.ts

@@ -30,7 +30,7 @@ export function pruneHistory(
   return store.transaction(() => {
     let removed = previousSources === undefined && pruneRuns(store, runs);
     for (const source of store.all(
-      `SELECT id,path FROM sources WHERE id NOT IN (SELECT source_id FROM children WHERE source_id IS NOT NULL)${previousSources ? ` AND id IN (${previousSources.map(() => "?").join(",")})` : ""}`,
+      `SELECT id,path FROM sources WHERE NOT EXISTS (SELECT 1 FROM children WHERE children.source_id=sources.id)${previousSources ? ` AND id IN (${previousSources.map(() => "?").join(",")})` : ""}`,
       ...(previousSources ?? []),
     )) {
       const id = text(source, "id");

package/src/history/run-projection.ts

@@ -147,10 +147,8 @@ export function projectRun(
   foreground: Readonly<ReadonlyMap<string, ReadonlyForegroundResumeRun>>,
 ): HistoryRunRow {
   const state: OwnedRunReadState = { ownedRuns: runs, foregroundRuns: foreground };
-  const questions = listRunQuestions(getRunMetadataDir(run.runId)).filter(
-    (question) =>
-      question.ownerSessionId === ownerSessionId &&
-      ["awaiting_input", "answer_pending"].includes(question.state),
+  const questions = listRunQuestions(getRunMetadataDir(run.runId), ownerSessionId).filter(
+    (question) => ["awaiting_input", "answer_pending"].includes(question.state),
   );
   return {
     ...ownedRunView(run, state, {

package/src/history/search-queries.ts

@@ -93,7 +93,8 @@ function plan(
     clauses.push("c.agent=?");
     params.push(input.agent);
   }
-  // Scope physical records once before aggregation; bm25 still uses the whole corpus.
+  // Materialized IDs reject common out-of-scope postings without per-hit entry lookups.
+  // Each source is scoped once; bm25 still uses the whole corpus.
   const eligible =
     hasText(input.runId) || hasText(input.agent)
       ? `eligible AS MATERIALIZED (SELECT e.rowid FROM entries e JOIN sources s ON s.id=e.source_id WHERE e.published=1 AND e.generation=s.generation AND e.source_id IN (SELECT c.source_id FROM children c WHERE ${clauses.slice(4).join(" AND ")})),`
@@ -166,6 +167,12 @@ export class SearchQueries {
     limit: number,
   ): readonly Row[] {
     // Match every token across a record's visible windows; a quoted phrase cannot span fields.
+    // Relevance benefits from hit-driven attribution. Newest keeps the native join order:
+    // forcing hit order regresses newest sorting across many shared attempts.
+    const joined =
+      score === "matched.score"
+        ? "FROM matched CROSS JOIN entries e ON e.rowid=matched.entry_rowid CROSS JOIN sources s ON s.id=e.source_id CROSS JOIN children c ON c.source_id=s.id JOIN excerpts ON excerpts.entry_rowid=matched.entry_rowid AND excerpts.choice=1 JOIN documents d ON d.id=excerpts.id"
+        : "FROM matched JOIN excerpts ON excerpts.entry_rowid=matched.entry_rowid AND excerpts.choice=1 JOIN documents d ON d.id=excerpts.id JOIN entries e ON e.rowid=matched.entry_rowid JOIN sources s ON s.id=e.source_id JOIN children c ON c.source_id=s.id";
     // Ranking/filters precede LIMIT. The parent owns the hard deadline for a costly FTS scan.
     return this.scope.store.all(
       `WITH ${filter.eligible} hits AS MATERIALIZED (
@@ -173,7 +180,7 @@ export class SearchQueries {
     ), terms AS (SELECT entry_rowid,term,MIN(score) AS score FROM hits GROUP BY entry_rowid,term),
     matched AS (SELECT entry_rowid,SUM(score) AS score FROM terms GROUP BY entry_rowid HAVING COUNT(*)=${expression.length}),
     excerpts AS (SELECT id,entry_rowid,ROW_NUMBER() OVER (PARTITION BY entry_rowid ORDER BY score,id) AS choice FROM hits)
-    SELECT d.*,${score} AS score,e.*,d.id AS document_id,s.path,s.session_id,c.run_id,c.child_index,c.agent,d.preview AS document_preview FROM matched JOIN excerpts ON excerpts.entry_rowid=matched.entry_rowid AND excerpts.choice=1 JOIN documents d ON d.id=excerpts.id JOIN entries e ON e.rowid=matched.entry_rowid JOIN sources s ON s.id=e.source_id JOIN children c ON c.source_id=s.id LEFT JOIN entries terminal ON terminal.source_id=s.id AND terminal.generation=s.generation AND terminal.id=c.terminal_entry_id AND terminal.published=1 WHERE ${filter.clauses.join(" AND ")} ORDER BY score,d.id,c.run_id,c.child_index LIMIT ?`,
+    SELECT d.*,${score} AS score,e.*,d.id AS document_id,s.path,s.session_id,c.run_id,c.child_index,c.agent,d.preview AS document_preview ${joined} LEFT JOIN entries terminal ON terminal.source_id=s.id AND terminal.generation=s.generation AND terminal.id=c.terminal_entry_id AND terminal.published=1 WHERE ${filter.clauses.join(" AND ")} ORDER BY score,d.id,c.run_id,c.child_index LIMIT ?`,
       ...filter.eligibleParams,
       ...filter.params,
       limit + 1,

package/src/history/store.ts

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { openGeneration } from "./database-generation.ts";
 import { OutputDigests } from "./output-digests.ts";
-import type { DatabaseSync } from "node:sqlite";
+import type { DatabaseSync, StatementSync } from "node:sqlite";
 import { historyTransaction, openHistoryDatabase } from "./database.ts";
 import { hash, safeText, hasText } from "./text.ts";
 export { hash, exactTextDigest, safeText, integer, pageLimit } from "./text.ts";
@@ -45,6 +45,7 @@ export class HistoryStore {
     this.counters[operation] += amount;
   }
   private ingestLock?: DatabaseSync;
+  private readonly statements = new Map<string, StatementSync>();
   private readonly outputDigests = new OutputDigests();
   constructor(agentDir: string, owner: string) {
     this.owner = owner;
@@ -72,12 +73,11 @@ export class HistoryStore {
     return row;
   }
   get(sql: string, ...params: readonly IndexInput[]): Row | undefined {
-    const row = this.db.prepare(sql).get(...params);
+    const row = this.statement(sql).get(...params);
     return row === undefined ? undefined : indexRow(row);
   }
   all(sql: string, ...params: readonly IndexInput[]): readonly Row[] {
-    return this.db
-      .prepare(sql)
+    return this.statement(sql)
       .all(...params)
       .map(indexRow);
   }
@@ -85,7 +85,22 @@ export class HistoryStore {
     sql: string,
     ...params: readonly IndexInput[]
   ): ReturnType<ReturnType<DatabaseSync["prepare"]>["run"]> {
-    return this.db.prepare(sql).run(...params);
+    return this.statement(sql).run(...params);
+  }
+  private statement(sql: string): StatementSync {
+    let statement = this.statements.get(sql);
+    if (!statement) {
+      statement = this.db.prepare(sql);
+      // Dynamic browse/filter shapes cannot grow this connection's cache indefinitely.
+      if (this.statements.size >= 128) {
+        const oldest = this.statements.keys().next().value;
+        if (oldest !== undefined) {
+          this.statements.delete(oldest);
+        }
+      }
+      this.statements.set(sql, statement);
+    }
+    return statement;
   }
   deleteDocuments(sourceId: string, unpublishedOnly = false): void {
     const where = `entry_rowid IN (SELECT rowid FROM entries WHERE source_id=?${unpublishedOnly ? " AND published=0" : ""})`;
@@ -279,6 +294,7 @@ export class HistoryStore {
     }
   }
   close(): void {
+    this.statements.clear();
     this.ingestLock?.close();
     this.db.close();
   }

package/src/history/text-chunks.ts

@@ -171,9 +171,14 @@ export class TextChunks {
       this.fields.clear();
     }
     if (this.staged.length > 0) {
-      const insert = store.db.prepare("INSERT INTO pending_text VALUES (?,?,?,?)");
       for (const item of this.staged) {
-        insert.run(item.field, item.start, item.end, item.text);
+        store.run(
+          "INSERT INTO pending_text VALUES (?,?,?,?)",
+          item.field,
+          item.start,
+          item.end,
+          item.text,
+        );
       }
       this.staged = [];
     }

package/src/history/transcript-queries.ts

@@ -58,7 +58,7 @@ export class TranscriptQueries {
     boundary: Boundary,
     ids: readonly string[],
   ): readonly (readonly [string, boolean])[] {
-    const delivered: (readonly [string, boolean])[] = [];
+    const humans: (readonly [string, number])[] = [];
     const where = boundary.clauses.join(" AND ");
     for (const id of new Set(ids)) {
       const human = this.scope.store.get(
@@ -67,17 +67,23 @@ export class TranscriptQueries {
         id,
       );
       if (human) {
-        delivered.push([
-          id,
-          this.scope.store.get(
-            `SELECT rowid FROM entries WHERE ${where} AND start>? AND assistant_text=1 LIMIT 1`,
-            ...boundary.params,
-            number(human, "start"),
-          ) !== undefined,
-        ]);
+        humans.push([id, number(human, "start")]);
       }
     }
-    return delivered;
+    if (humans.length === 0) {
+      return [];
+    }
+    // One tail lookup answers every ID, without scanning before the earliest requested human.
+    const assistant = this.scope.store.get(
+      `SELECT start FROM entries WHERE ${where} AND start>? AND assistant_text=1 ORDER BY start DESC LIMIT 1`,
+      ...boundary.params,
+      Math.min(...humans.map(([, start]) => start)),
+    );
+    const assistantStart = assistant ? number(assistant, "start") : undefined;
+    return humans.map(([id, start]): readonly [string, boolean] => [
+      id,
+      assistantStart !== undefined && start < assistantStart,
+    ]);
   }
   private readMetadata(
     boundary: Boundary,

package/src/intercom/result-intercom.ts

@@ -1,5 +1,4 @@
 import type { ReadonlyInput } from "../shared/types/inputs.ts";
-import { copyDetails, copyResult } from "../extension/result-snapshot.ts";
 import { compactNestedResultChildren, formatNestedResultLines } from "./nested-result-tree.ts";
 export {
   compactNestedResultChildren,
@@ -13,7 +12,6 @@ import * as fs from "node:fs";
 import { formatRunAction } from "../shared/status-format.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import type {
-  Details,
   SingleResult,
   SubagentResultIntercomChild,
   SubagentResultIntercomPayload,
@@ -308,104 +306,3 @@ export function buildSubagentResultIntercomPayload(
   };
   return { ...payload, message: formatSubagentResultIntercomMessage(payload) };
 }
-
-function stripSingleResultOutputs(result: ReadonlyInput<SingleResult>): SingleResult {
-  return {
-    ...copyResult(result),
-    messages: undefined,
-    finalOutput: undefined,
-    truncation: undefined,
-  };
-}
-
-export function stripDetailsOutputsForIntercomReceipt(
-  details: ReadonlyInput<Details>,
-  delivery?: Details["intercomDelivery"],
-): Details {
-  return {
-    ...copyDetails(details),
-    results: details.results.map(stripSingleResultOutputs),
-    ...(delivery ? { intercomDelivery: delivery } : {}),
-  };
-}
-
-function compactReceiptSummary(summary: string): string {
-  const withoutOutput = summary.split(/\n\nOutput:\n|\sOutput:\s/)[0] ?? summary;
-  const normalized = withoutOutput.replace(/\s+/g, " ").trim();
-  return normalized.length > 240 ? `${normalized.slice(0, 239)}…` : normalized;
-}
-
-function formatChildReferences(
-  children: readonly SubagentResultIntercomChild[],
-  field: "artifactPath" | "intercomTarget" | "sessionPath",
-  heading: string,
-): string[] {
-  const lines: string[] = [];
-  for (const child of children) {
-    const value = child[field];
-    if (typeof value === "string") {
-      lines.push(`- ${child.agent} [${child.status}]: ${value}`);
-    }
-  }
-  return lines.length > 0 ? [heading, ...lines] : [];
-}
-
-function formatReceiptReferences(payload: SubagentResultIntercomPayload): string[] {
-  const lines: string[] = [];
-  if (hasText(payload.resultPath)) {
-    lines.push(`Saved result (acceptance details when configured): ${payload.resultPath}`);
-  }
-  for (const child of payload.children) {
-    if (hasText(child.metadataPath)) {
-      lines.push(
-        `Result metadata (${child.agent}; acceptance details when configured): ${child.metadataPath}${fs.existsSync(child.metadataPath) ? "" : " (missing)"}`,
-      );
-    }
-  }
-  lines.push(
-    ...formatChildReferences(payload.children, "artifactPath", "Artifacts:"),
-    ...formatChildReferences(
-      payload.children,
-      "intercomTarget",
-      "Run intercom targets (may be inactive after completion):",
-    ),
-    ...formatChildReferences(payload.children, "sessionPath", "Sessions:"),
-  );
-  const nonCompleted = payload.children.filter((child) => child.status !== "completed");
-  if (nonCompleted.length > 0) {
-    lines.push("Non-completed children:");
-    for (const child of nonCompleted) {
-      lines.push(`- ${child.agent} [${child.status}]: ${compactReceiptSummary(child.summary)}`);
-    }
-  }
-  return lines;
-}
-
-export function formatSubagentResultReceipt(input: {
-  readonly mode: SubagentRunMode;
-  readonly runId: string;
-  readonly payload: SubagentResultIntercomPayload;
-}): string {
-  const counts = countStatuses(input.payload.children);
-  const modeLabel = {
-    single: "single subagent result",
-    parallel: "parallel subagent results",
-    chain: "chain subagent results",
-  }[input.mode];
-  const lines = [
-    `Delivered ${modeLabel} via intercom.`,
-    "Delivery: succeeded",
-    `Run: ${input.runId}`,
-    `Child outcome: ${input.payload.status}`,
-    `Children: ${formatStatusCounts(counts)}`,
-    ...(hasText(input.payload.error)
-      ? [
-          `Workflow ${input.payload.status === "paused" ? "paused" : "error"}: ${input.payload.error}`,
-        ]
-      : []),
-  ];
-
-  lines.push(...formatReceiptReferences(input.payload));
-  lines.push("Full grouped output was sent over intercom.");
-  return lines.join("\n");
-}

package/src/pi-intercom/broker/broker.ts

@@ -23,7 +23,7 @@ import { errorMessage, isRecord, type UnknownRecord } from "../../shared/unknown
 import {
   messageSender,
   snapshotFrames,
-  prepareTopicChange,
+  TopicSnapshot,
   publicationMessage,
   deliveryAcknowledgement,
   shouldReplaceDelivery,
@@ -36,6 +36,7 @@ const REPLACE_DELIVERY_DELAY_MS = 1500;
 interface ConnectedSession {
   readonly socket: net.Socket;
   info: SessionInfo;
+  topics: TopicSnapshot;
   readonly topicFrames: boolean;
 }
 
@@ -178,7 +179,12 @@ class IntercomBroker {
     const info: SessionInfo = { ...msg.session, id, lastSeen: msg.session.lastSeen ?? Date.now() };
     snapshotFrames(randomUUID(), [info], true);
     const topicFrames = msg.topicFrames === true;
-    this.sessions.set(id, { socket, info, topicFrames });
+    this.sessions.set(id, {
+      socket,
+      info: messageSender(info),
+      topics: new TopicSnapshot(info),
+      topicFrames,
+    });
     setId(id);
     if (this.shutdownTimer) {
       clearTimeout(this.shutdownTimer);
@@ -208,9 +214,7 @@ class IntercomBroker {
       return deliveries;
     }
     for (const target of this.sessions.values()) {
-      const subscription = target.info.subscriptions?.find(
-        (entry) => entry.topic === publication.topic,
-      );
+      const subscription = target.topics.subscription(publication.topic);
       if (target.info.id === fromId || !subscription) {
         continue;
       }
@@ -234,24 +238,28 @@ class IntercomBroker {
       if (!session) {
         throw new Error("Sender session not found");
       }
-      const prepared = prepareTopicChange(session.info, msg.change, session.topicFrames);
-      const nextInfo = prepared.info;
+      const prepared = session.topics.prepare(msg.change, session.topicFrames);
+      const nextInfo = prepared.restore
+        ? session.info
+        : session.topics.snapshot(session.info, prepared);
       const from = messageSender(nextInfo);
       const deliveries = this.planPublications(currentId, from, prepared.publication);
-      const restore = prepared.restore;
-      const infos = [...this.sessions.values()].map((entry) =>
-        entry === session ? nextInfo : entry.info,
-      );
       // Validate every frame before committing state or delivering publications.
-      if (restore) {
-        snapshotFrames(requestId, [nextInfo], true);
+      if (prepared.restore) {
+        session.topics.validateRestore(session.info, prepared, requestId);
       }
-      const frames = snapshotFrames(requestId, restore ? [] : infos, msg.stream === true);
+      const infos = prepared.restore
+        ? []
+        : [...this.sessions.values()].map((entry) => {
+            if (entry === session) {
+              return nextInfo;
+            }
+            return msg.stream === true ? entry.topics.snapshot(entry.info) : entry.info;
+          });
+      const frames = snapshotFrames(requestId, infos, msg.stream === true);
       const last = frames.pop();
-      if (!last) {
-        throw new Error("Missing final snapshot frame");
-      }
-      session.info = nextInfo;
+      session.topics.commit(prepared);
+      session.info = messageSender(nextInfo);
       const receipts: Array<SessionSnapshot["receipts"][number]> = [];
       for (const { to, message } of deliveries) {
         receipts.push({ to, ...this.sendToSession(currentId, to, from, message) });
@@ -326,7 +334,10 @@ class IntercomBroker {
     if (!session) {
       return;
     }
-    const update: Record<string, unknown> = { ...session.info, lastSeen: Date.now() };
+    const update: Record<string, unknown> = {
+      ...session.topics.snapshot(session.info),
+      lastSeen: Date.now(),
+    };
     for (const key of [
       "name",
       "status",
@@ -346,7 +357,10 @@ class IntercomBroker {
       throw new Error("Invalid presence update");
     }
     snapshotFrames(randomUUID(), [nextInfo], true);
-    session.info = nextInfo;
+    if (msg.topics !== undefined || msg.subscriptions !== undefined) {
+      session.topics = new TopicSnapshot(nextInfo);
+    }
+    session.info = messageSender(nextInfo);
   }
 
   private sendToSession(

package/src/pi-intercom/broker/framing.ts

@@ -19,17 +19,67 @@ export function validateIntercomMessageSize(msg: unknown): Error | null {
  * Format: 4-byte big-endian length + JSON payload
  */
 export function writeMessage(socket: Socket, msg: unknown): void {
-  const tooLarge = validateIntercomMessageSize(msg);
-  if (tooLarge) {
-    throw tooLarge;
-  }
   const json = JSON.stringify(msg);
+  const size = Buffer.byteLength(json, "utf-8");
+  if (size > MAX_FRAME_SIZE_BYTES) {
+    throw new Error(`Intercom message too large (${size} bytes; max ${MAX_FRAME_SIZE_BYTES})`);
+  }
   const payload = Buffer.from(json, "utf-8");
   const header = Buffer.alloc(4);
   header.writeUInt32BE(payload.length, 0);
   socket.write(Buffer.concat([header, payload]));
 }
 
+/** Retain fragments until a header or payload is complete; copy each fragmented value once. */
+class MessageBuffer {
+  private chunks: Buffer[] = [];
+  private index = 0;
+  length = 0;
+
+  append(data: Buffer): void {
+    if (data.length > 0) {
+      this.chunks.push(data);
+      this.length += data.length;
+    }
+  }
+
+  clear(): void {
+    this.chunks = [];
+    this.index = 0;
+    this.length = 0;
+  }
+
+  read(size: number): Buffer {
+    const first = this.chunks[this.index];
+    if (size === 0) {
+      return Buffer.alloc(0);
+    }
+    const result = first.length >= size ? first.subarray(0, size) : Buffer.allocUnsafe(size);
+    let written = 0;
+    while (written < size) {
+      const chunk = this.chunks[this.index];
+      const count = Math.min(chunk.length, size - written);
+      if (first.length < size) {
+        chunk.copy(result, written, 0, count);
+      }
+      written += count;
+      this.length -= count;
+      if (count === chunk.length) {
+        this.index++;
+      } else {
+        this.chunks[this.index] = chunk.subarray(count);
+      }
+    }
+    if (this.index === this.chunks.length) {
+      this.clear();
+    } else if (this.index * 2 >= this.chunks.length) {
+      this.chunks = this.chunks.slice(this.index);
+      this.index = 0;
+    }
+    return result;
+  }
+}
+
 /**
  * Create a message reader that handles partial reads.
  * Calls onMessage for each complete message received.
@@ -39,27 +89,28 @@ export function createMessageReader(
   onMessage: (msg: unknown) => void,
   onError: (error: Readonly<Error>) => void,
 ): (data: Buffer) => void {
-  let buffer = Buffer.alloc(0);
+  const buffer = new MessageBuffer();
+  let length: number | undefined;
 
   return (data: Buffer) => {
-    buffer = Buffer.concat([buffer, data]);
-
-    while (buffer.length >= 4) {
-      const length = buffer.readUInt32BE(0);
-      if (length > MAX_FRAME_SIZE_BYTES) {
-        onError(
-          new Error(`Intercom frame too large (${length} bytes; max ${MAX_FRAME_SIZE_BYTES})`),
-        );
-        buffer = Buffer.alloc(0);
-        return;
-      }
+    buffer.append(data);
 
-      if (buffer.length < 4 + length) {
-        break;
+    while (buffer.length >= (length ?? 4)) {
+      if (length === undefined) {
+        length = buffer.read(4).readUInt32BE(0);
+        if (length > MAX_FRAME_SIZE_BYTES) {
+          onError(
+            new Error(`Intercom frame too large (${length} bytes; max ${MAX_FRAME_SIZE_BYTES})`),
+          );
+          buffer.clear();
+          length = undefined;
+          return;
+        }
+        continue;
       }
 
-      const payload = buffer.subarray(4, 4 + length);
-      buffer = buffer.subarray(4 + length);
+      const payload = buffer.read(length);
+      length = undefined;
 
       let msg: unknown;
       try {