@poncho-ai/harness 0.57.0 → 0.58.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.57.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.58.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js            565.81 KB
+ESM dist/index.js            567.32 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM ⚡️ Build success in 254ms
+ESM ⚡️ Build success in 177ms
 DTS Build start
-DTS ⚡️ Build success in 7133ms
+DTS ⚡️ Build success in 7320ms
 DTS dist/index.d.ts 104.68 KB

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @poncho-ai/harness
 
+## 0.58.0
+
+### Minor Changes
+
+- [#155](https://github.com/cesr/poncho-ai/pull/155) [`9939955`](https://github.com/cesr/poncho-ai/commit/9939955585f0ea204e070192827f0b213e84d283) Thanks [@cesr](https://github.com/cesr)! - Phase 3c read cutover: conversation reads rebuild from the append-only
+  `conversation_entries` log. Both engines' `get`/`getWithArchive` paths now
+  call `rebuildConversationFromEntries`, which overrides `_harnessMessages`
+  (via `buildLlmContext`), `messages` (via `buildDisplaySnapshot`, full
+  transcript), and `pendingSubagentResults` (via `getPendingSubagentResults`)
+  when the entry log is non-empty. Conversations that predate dual-write have
+  no entries and fall back to the mutable blob untouched — no migration
+  script needed. The rebuild is wrapped in try/catch and never throws on the
+  read path. A kill-switch (`PONCHO_READ_ENTRIES=0`) instantly reverts to
+  blob reads without a deploy. `_continuationMessages` and `pendingApprovals`
+  remain blob fields (not yet modeled as entries).
+
 ## 0.57.0
 
 ### Minor Changes

package/dist/index.js

@@ -2443,7 +2443,7 @@ var ponchoDocsTool = defineTool({
 import { randomUUID as randomUUID5 } from "crypto";
 import { readFile as readFile9 } from "fs/promises";
 import { resolve as resolve11 } from "path";
-import { defineTool as defineTool12, getTextContent as getTextContent2, createLogger as createLogger6, formatError as fmtErr, url as urlColor } from "@poncho-ai/sdk";
+import { defineTool as defineTool12, getTextContent as getTextContent2, createLogger as createLogger7, formatError as fmtErr, url as urlColor } from "@poncho-ai/sdk";
 
 // src/upload-store.ts
 import { createHash as createHash2 } from "crypto";
@@ -2776,6 +2776,87 @@ var createUploadStore = async (config, workingDir) => {
 
 // src/storage/memory-engine.ts
 import { randomUUID as randomUUID3 } from "crypto";
+
+// src/storage/entries.ts
+import { createLogger as createLogger2 } from "@poncho-ai/sdk";
+var entriesReadLog = createLogger2("entries-read");
+function buildLlmContext(entries) {
+  let latestCompaction;
+  for (const e of entries) {
+    if (e.type === "compaction" && (!latestCompaction || e.seq > latestCompaction.seq)) {
+      latestCompaction = e;
+    }
+  }
+  const harnessMsgs = entries.filter(
+    (e) => e.type === "harness_message"
+  );
+  if (latestCompaction) {
+    const kept = harnessMsgs.filter((e) => e.seq >= latestCompaction.firstKeptSeq).map((e) => e.message);
+    return [latestCompaction.summaryMessage, ...kept];
+  }
+  return harnessMsgs.map((e) => e.message);
+}
+function buildDisplaySnapshot(entries, tailN) {
+  const amendmentsByTarget = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (e.type === "assistant_amendment") {
+      const list = amendmentsByTarget.get(e.targetEntryId) ?? [];
+      list.push(e);
+      amendmentsByTarget.set(e.targetEntryId, list);
+    }
+  }
+  const built = [];
+  for (const e of entries) {
+    if (e.type === "user_message") {
+      if (e.hidden) continue;
+      built.push({ seq: e.seq, message: e.message });
+    } else if (e.type === "assistant_message") {
+      let content = typeof e.message.content === "string" ? e.message.content : "";
+      const amendments = amendmentsByTarget.get(e.id);
+      if (amendments) {
+        for (const a of amendments.sort((x, y) => x.seq - y.seq)) {
+          if (a.appendText) content += a.appendText;
+        }
+      }
+      built.push({ seq: e.seq, message: { ...e.message, content } });
+    }
+  }
+  const total = built.length;
+  const tail = tailN >= total ? built : built.slice(total - tailN);
+  return {
+    messages: tail.map((b) => b.message),
+    totalMessages: total,
+    headSeq: tail.length > 0 ? tail[0].seq : null
+  };
+}
+function getPendingSubagentResults(entries) {
+  const consumed = /* @__PURE__ */ new Set();
+  for (const e of entries) {
+    if (e.type === "callback_started") {
+      for (const s of e.consumedSeqs) consumed.add(s);
+    }
+  }
+  return entries.filter((e) => e.type === "subagent_result").filter((e) => !consumed.has(e.seq)).map((e) => e.result);
+}
+var FULL_TRANSCRIPT_TAIL = 1e5;
+async function rebuildConversationFromEntries(conversation, readEntries) {
+  if (process.env.PONCHO_READ_ENTRIES === "0") return conversation;
+  try {
+    const entries = await readEntries(conversation.conversationId);
+    if (entries.length === 0) return conversation;
+    conversation._harnessMessages = buildLlmContext(entries);
+    conversation.messages = buildDisplaySnapshot(entries, FULL_TRANSCRIPT_TAIL).messages;
+    conversation.pendingSubagentResults = getPendingSubagentResults(entries);
+    return conversation;
+  } catch (err) {
+    entriesReadLog.warn(
+      `[entries-read] ${conversation.conversationId} rebuild failed, using blob: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return conversation;
+  }
+}
+
+// src/storage/memory-engine.ts
 var DEFAULT_TENANT = "__default__";
 var DEFAULT_OWNER = "local-owner";
 var normalizeTenant = (tenantId) => tenantId ?? DEFAULT_TENANT;
@@ -2826,12 +2907,22 @@ var InMemoryEngine = class {
       return results;
     },
     get: async (conversationId) => {
-      return this.convs.get(conversationId);
+      const c = this.convs.get(conversationId);
+      if (!c) return void 0;
+      return rebuildConversationFromEntries(
+        { ...c },
+        (id) => this.conversations.readEntries(id)
+      );
     },
     // In-memory storage has no separate archive blob, so both variants
     // return the same conversation object.
     getWithArchive: async (conversationId) => {
-      return this.convs.get(conversationId);
+      const c = this.convs.get(conversationId);
+      if (!c) return void 0;
+      return rebuildConversationFromEntries(
+        { ...c },
+        (id) => this.conversations.readEntries(id)
+      );
     },
     getStatusSnapshot: async (conversationId) => {
       const c = this.convs.get(conversationId);
@@ -3292,7 +3383,7 @@ import { dirname as dirname2, resolve as resolve6 } from "path";
 
 // src/storage/sql-dialect.ts
 import { randomUUID as randomUUID4 } from "crypto";
-import { createLogger as createLogger2 } from "@poncho-ai/sdk";
+import { createLogger as createLogger3 } from "@poncho-ai/sdk";
 
 // src/storage/schema.ts
 var migrations = [
@@ -3517,7 +3608,7 @@ var migrations = [
 ];
 
 // src/storage/sql-dialect.ts
-var egressLog = createLogger2("egress");
+var egressLog = createLogger3("egress");
 var sqliteDialect = {
   tag: "sqlite",
   param: () => "?",
@@ -3707,7 +3798,10 @@ var SqlStorageEngine = class {
       if (row.continuation_messages) {
         conv._continuationMessages = typeof row.continuation_messages === "string" ? JSON.parse(row.continuation_messages) : row.continuation_messages;
       }
-      return conv;
+      return rebuildConversationFromEntries(
+        conv,
+        (id) => this.conversations.readEntries(id)
+      );
     },
     getStatusSnapshot: async (conversationId) => {
       const runStatusExpr = this.dialect.tag === "sqlite" ? "json_extract(data, '$.runStatus')" : "data->>'runStatus'";
@@ -3757,7 +3851,10 @@ var SqlStorageEngine = class {
       if (row.continuation_messages) {
         conv._continuationMessages = typeof row.continuation_messages === "string" ? JSON.parse(row.continuation_messages) : row.continuation_messages;
       }
-      return conv;
+      return rebuildConversationFromEntries(
+        conv,
+        (id) => this.conversations.readEntries(id)
+      );
     },
     create: async (ownerId, title, tenantId, init) => {
       const id = randomUUID4();
@@ -6580,8 +6677,8 @@ var createReminderTools = (store) => [
 ];
 
 // src/mcp.ts
-import { createLogger as createLogger3 } from "@poncho-ai/sdk";
-var mcpLog = createLogger3("mcp");
+import { createLogger as createLogger4 } from "@poncho-ai/sdk";
+var mcpLog = createLogger4("mcp");
 var McpHttpError = class extends Error {
   status;
   constructor(status, message) {
@@ -7574,8 +7671,8 @@ var createModelProvider = (provider, config) => {
 import { readFile as readFile8, readdir as readdir3, stat as stat2 } from "fs/promises";
 import { dirname as dirname5, resolve as resolve9, normalize as normalize2 } from "path";
 import YAML3 from "yaml";
-import { createLogger as createLogger4 } from "@poncho-ai/sdk";
-var logger = createLogger4("skills");
+import { createLogger as createLogger5 } from "@poncho-ai/sdk";
+var logger = createLogger5("skills");
 var DEFAULT_SKILL_DIRS = ["skills"];
 var resolveSkillDirs = (workingDir, extraPaths) => {
   const dirs = [...DEFAULT_SKILL_DIRS];
@@ -8691,9 +8788,9 @@ import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 
 // src/telemetry.ts
-import { createLogger as createLogger5 } from "@poncho-ai/sdk";
-var eventLog = createLogger5("event");
-var telemetryLog = createLogger5("telemetry");
+import { createLogger as createLogger6 } from "@poncho-ai/sdk";
+var eventLog = createLogger6("event");
+var telemetryLog = createLogger6("telemetry");
 var MAX_FIELD_LENGTH = 200;
 var OMIT_FROM_LOG = /* @__PURE__ */ new Set(["continuationMessages", "_harnessMessages", "messages", "compactedHistory"]);
 function sanitizeEventForLog(event) {
@@ -8864,11 +8961,11 @@ var ToolDispatcher = class {
 };
 
 // src/harness.ts
-var harnessLog = createLogger6("harness");
-var telemetryLog2 = createLogger6("telemetry");
-var costLog = createLogger6("cost");
-var mcpLog2 = createLogger6("mcp");
-var modelLog = createLogger6("model");
+var harnessLog = createLogger7("harness");
+var telemetryLog2 = createLogger7("telemetry");
+var costLog = createLogger7("cost");
+var mcpLog2 = createLogger7("mcp");
+var modelLog = createLogger7("model");
 function formatOtlpError(err) {
   if (!(err instanceof Error)) return String(err);
   const parts = [];
@@ -9840,7 +9937,7 @@ var AgentHarness = class _AgentHarness {
       const key = `${effectiveTenant}:${skipped.name}`;
       if (this.vfsSkillCollisionWarnings.has(key)) return;
       this.vfsSkillCollisionWarnings.add(key);
-      createLogger6("skills").warn(
+      createLogger7("skills").warn(
         `VFS skill "${skipped.name}" for tenant ${effectiveTenant} ignored: a repo skill with the same name takes precedence.`
       );
     });
@@ -10093,7 +10190,7 @@ var AgentHarness = class _AgentHarness {
       this.agentFileFingerprint = rawContent;
       return true;
     } catch (error) {
-      createLogger6("agent").warn(`failed to refresh AGENT.md in dev: ${fmtErr(error)}`);
+      createLogger7("agent").warn(`failed to refresh AGENT.md in dev: ${fmtErr(error)}`);
       return false;
     }
   }
@@ -10141,7 +10238,7 @@ var AgentHarness = class _AgentHarness {
       await this.refreshMcpTools("skills:changed");
       return true;
     } catch (error) {
-      createLogger6("skills").warn(`failed to refresh skills in dev: ${fmtErr(error)}`);
+      createLogger7("skills").warn(`failed to refresh skills in dev: ${fmtErr(error)}`);
       return false;
     }
   }
@@ -10251,7 +10348,7 @@ var AgentHarness = class _AgentHarness {
     }
     if (config?.browser) {
       await this.initBrowserTools(config).catch((e) => {
-        createLogger6("browser").warn(`failed to load browser tools: ${fmtErr(e)}`);
+        createLogger7("browser").warn(`failed to load browser tools: ${fmtErr(e)}`);
       });
     }
     const stateConfig = resolveStateConfig(config);
@@ -12149,7 +12246,9 @@ var InMemoryConversationStore = class {
   }
   async get(conversationId) {
     this.purgeExpired();
-    return this.conversations.get(conversationId);
+    const c = this.conversations.get(conversationId);
+    if (!c) return void 0;
+    return rebuildConversationFromEntries({ ...c }, (id) => this.readEntries(id));
   }
   // In-memory stores already hold the full conversation object, so there's
   // no separate archive blob to load. Both variants return the same data.
@@ -12276,66 +12375,6 @@ var createConversationStore = (config, _options) => {
   return new InMemoryConversationStore(ttl);
 };
 
-// src/storage/entries.ts
-function buildLlmContext(entries) {
-  let latestCompaction;
-  for (const e of entries) {
-    if (e.type === "compaction" && (!latestCompaction || e.seq > latestCompaction.seq)) {
-      latestCompaction = e;
-    }
-  }
-  const harnessMsgs = entries.filter(
-    (e) => e.type === "harness_message"
-  );
-  if (latestCompaction) {
-    const kept = harnessMsgs.filter((e) => e.seq >= latestCompaction.firstKeptSeq).map((e) => e.message);
-    return [latestCompaction.summaryMessage, ...kept];
-  }
-  return harnessMsgs.map((e) => e.message);
-}
-function buildDisplaySnapshot(entries, tailN) {
-  const amendmentsByTarget = /* @__PURE__ */ new Map();
-  for (const e of entries) {
-    if (e.type === "assistant_amendment") {
-      const list = amendmentsByTarget.get(e.targetEntryId) ?? [];
-      list.push(e);
-      amendmentsByTarget.set(e.targetEntryId, list);
-    }
-  }
-  const built = [];
-  for (const e of entries) {
-    if (e.type === "user_message") {
-      if (e.hidden) continue;
-      built.push({ seq: e.seq, message: e.message });
-    } else if (e.type === "assistant_message") {
-      let content = typeof e.message.content === "string" ? e.message.content : "";
-      const amendments = amendmentsByTarget.get(e.id);
-      if (amendments) {
-        for (const a of amendments.sort((x, y) => x.seq - y.seq)) {
-          if (a.appendText) content += a.appendText;
-        }
-      }
-      built.push({ seq: e.seq, message: { ...e.message, content } });
-    }
-  }
-  const total = built.length;
-  const tail = tailN >= total ? built : built.slice(total - tailN);
-  return {
-    messages: tail.map((b) => b.message),
-    totalMessages: total,
-    headSeq: tail.length > 0 ? tail[0].seq : null
-  };
-}
-function getPendingSubagentResults(entries) {
-  const consumed = /* @__PURE__ */ new Set();
-  for (const e of entries) {
-    if (e.type === "callback_started") {
-      for (const s of e.consumedSeqs) consumed.add(s);
-    }
-  }
-  return entries.filter((e) => e.type === "subagent_result").filter((e) => !consumed.has(e.seq)).map((e) => e.result);
-}
-
 // src/tenant-token.ts
 import { jwtVerify } from "jose";
 async function verifyTenantToken(signingKey, token) {
@@ -12668,7 +12707,7 @@ var CALLBACK_LOCK_STALE_MS = 5 * 60 * 1e3;
 var STALE_SUBAGENT_THRESHOLD_MS = 5 * 60 * 1e3;
 
 // src/orchestrator/orchestrator.ts
-import { createLogger as createLogger7, getTextContent as getTextContent4 } from "@poncho-ai/sdk";
+import { createLogger as createLogger8, getTextContent as getTextContent4 } from "@poncho-ai/sdk";
 
 // src/orchestrator/entries-dual-write.ts
 import { randomUUID as randomUUID6 } from "crypto";
@@ -12802,7 +12841,7 @@ var verifyEntriesParity = async (store, conversationId, blob, log2) => {
 };
 
 // src/orchestrator/orchestrator.ts
-var dualWriteLog = createLogger7("orchestrator:entries");
+var dualWriteLog = createLogger8("orchestrator:entries");
 var assistantMessageText = (message) => {
   const raw = getTextContent4(message).trim();
   if (raw.startsWith("{") && raw.includes('"tool_calls"')) {
@@ -14393,8 +14432,8 @@ ${resultBody}`,
 
 // src/orchestrator/run-conversation-turn.ts
 import { randomUUID as randomUUID7 } from "crypto";
-import { createLogger as createLogger8 } from "@poncho-ai/sdk";
-var log = createLogger8("orchestrator");
+import { createLogger as createLogger9 } from "@poncho-ai/sdk";
+var log = createLogger9("orchestrator");
 var runConversationTurn = async (opts) => {
   const conversation = await opts.conversationStore.getWithArchive(opts.conversationId);
   if (!conversation) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/state.ts

@@ -1,5 +1,9 @@
 import type { Message } from "@poncho-ai/sdk";
-import type { ConversationEntry, NewConversationEntry } from "./storage/entries.js";
+import {
+  type ConversationEntry,
+  type NewConversationEntry,
+  rebuildConversationFromEntries,
+} from "./storage/entries.js";
 
 export interface ConversationState {
   runId: string;
@@ -269,7 +273,12 @@ export class InMemoryConversationStore implements ConversationStore {
 
   async get(conversationId: string): Promise<Conversation | undefined> {
     this.purgeExpired();
-    return this.conversations.get(conversationId);
+    const c = this.conversations.get(conversationId);
+    if (!c) return undefined;
+    // Phase 3c read cutover: rebuild reader-facing fields from the entry log
+    // (blob fallback for un-migrated conversations). Clone first — the map
+    // holds a live mutable reference and the rebuild overrides fields.
+    return rebuildConversationFromEntries({ ...c }, (id) => this.readEntries(id));
   }
 
   // In-memory stores already hold the full conversation object, so there's

package/src/storage/entries.ts

@@ -1,5 +1,7 @@
-import type { Message } from "@poncho-ai/sdk";
-import type { PendingSubagentResult } from "../state.js";
+import { createLogger, type Message } from "@poncho-ai/sdk";
+import type { Conversation, PendingSubagentResult } from "../state.js";
+
+const entriesReadLog = createLogger("entries-read");
 
 /**
  * Append-only conversation entries (Phase 3 substrate).
@@ -215,3 +217,56 @@ export function getPendingSubagentResults(
     .filter((e) => !consumed.has(e.seq))
     .map((e) => e.result);
 }
+
+// A very large tail so the rebuilt display snapshot is the full transcript.
+// Display callers slice to whatever window they actually render.
+const FULL_TRANSCRIPT_TAIL = 100_000;
+
+/**
+ * Phase 3c read cutover: rebuild a conversation's reader-facing fields from
+ * the append-only entry log, with a blob fallback for conversations that
+ * predate dual-write.
+ *
+ * Call this in every conversation `get`/`getWithArchive` path AFTER the
+ * Conversation has been constructed from the stored row/blob. It:
+ *   - reads the entry log via `readEntries`,
+ *   - if NON-EMPTY, overrides `_harnessMessages`, `messages`, and
+ *     `pendingSubagentResults` with entry-derived values,
+ *   - if EMPTY (un-migrated conversation), leaves the blob-derived fields
+ *     untouched (fallback),
+ *   - on ANY error, logs and falls back to the blob (never throws — this is
+ *     a hot read path).
+ *
+ * `_continuationMessages` and `pendingApprovals` are NOT modeled as entries
+ * yet and are intentionally left as blob fields.
+ *
+ * Kill-switch: set `PONCHO_READ_ENTRIES=0` to instantly revert to pure blob
+ * reads without a deploy (rebuild is ON by default).
+ *
+ * NOTE: mutates `conversation` in place and returns it. Callers that hand
+ * back a shared/mutable Conversation reference (the in-memory stores) MUST
+ * pass a clone, or the override will corrupt their stored object.
+ */
+export async function rebuildConversationFromEntries(
+  conversation: Conversation,
+  readEntries: (conversationId: string) => Promise<ConversationEntry[]>,
+): Promise<Conversation> {
+  // Kill-switch: ON by default; PONCHO_READ_ENTRIES="0" reverts to blob reads.
+  if (process.env.PONCHO_READ_ENTRIES === "0") return conversation;
+
+  try {
+    const entries = await readEntries(conversation.conversationId);
+    if (entries.length === 0) return conversation; // fallback: pre-dual-write
+    conversation._harnessMessages = buildLlmContext(entries);
+    conversation.messages = buildDisplaySnapshot(entries, FULL_TRANSCRIPT_TAIL).messages;
+    conversation.pendingSubagentResults = getPendingSubagentResults(entries);
+    return conversation;
+  } catch (err) {
+    entriesReadLog.warn(
+      `[entries-read] ${conversation.conversationId} rebuild failed, using blob: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return conversation;
+  }
+}

package/src/storage/memory-engine.ts

@@ -14,7 +14,11 @@ import type { MainMemory } from "../memory.js";
 import type { TodoItem } from "../todo-tools.js";
 import type { Reminder, ReminderCreateInput, ReminderStatus } from "../reminder-store.js";
 import type { StorageEngine, VfsDirEntry, VfsStat } from "./engine.js";
-import type { ConversationEntry, NewConversationEntry } from "./entries.js";
+import {
+  type ConversationEntry,
+  type NewConversationEntry,
+  rebuildConversationFromEntries,
+} from "./entries.js";
 
 // ---------------------------------------------------------------------------
 // Internal VFS entry type
@@ -103,13 +107,24 @@ export class InMemoryEngine implements StorageEngine {
     },
 
     get: async (conversationId: string): Promise<Conversation | undefined> => {
-      return this.convs.get(conversationId);
+      const c = this.convs.get(conversationId);
+      if (!c) return undefined;
+      // Phase 3c read cutover: rebuild reader-facing fields from the entry
+      // log (blob fallback for un-migrated conversations). Clone first — the
+      // map holds a live mutable reference and the rebuild overrides fields.
+      return rebuildConversationFromEntries({ ...c }, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     // In-memory storage has no separate archive blob, so both variants
     // return the same conversation object.
     getWithArchive: async (conversationId: string): Promise<Conversation | undefined> => {
-      return this.convs.get(conversationId);
+      const c = this.convs.get(conversationId);
+      if (!c) return undefined;
+      return rebuildConversationFromEntries({ ...c }, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     getStatusSnapshot: async (

package/src/storage/sql-dialect.ts

@@ -22,7 +22,11 @@ import type { MainMemory } from "../memory.js";
 import type { TodoItem } from "../todo-tools.js";
 import type { Reminder, ReminderCreateInput, ReminderStatus } from "../reminder-store.js";
 import type { StorageEngine, VfsDirEntry, VfsStat } from "./engine.js";
-import type { ConversationEntry, NewConversationEntry } from "./entries.js";
+import {
+  type ConversationEntry,
+  type NewConversationEntry,
+  rebuildConversationFromEntries,
+} from "./entries.js";
 import { type DialectTag, migrations } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -325,7 +329,12 @@ export abstract class SqlStorageEngine implements StorageEngine {
             ? JSON.parse(row.continuation_messages)
             : row.continuation_messages;
       }
-      return conv;
+      // Phase 3c read cutover: rebuild reader-facing fields from the
+      // append-only entry log, falling back to the blob for un-migrated
+      // conversations. parseConversation returns a fresh object, so no clone.
+      return rebuildConversationFromEntries(conv, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     getStatusSnapshot: async (
@@ -408,7 +417,11 @@ export abstract class SqlStorageEngine implements StorageEngine {
             ? JSON.parse(row.continuation_messages)
             : row.continuation_messages;
       }
-      return conv;
+      // Phase 3c read cutover: rebuild reader-facing fields from the entry
+      // log (blob fallback for un-migrated conversations).
+      return rebuildConversationFromEntries(conv, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     create: async (

package/test/entries-read-cutover.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { InMemoryConversationStore } from "../src/state.js";
+import {
+  buildLlmContext,
+  buildDisplaySnapshot,
+  type NewConversationEntry,
+} from "../src/storage/entries.js";
+import type { Message } from "@poncho-ai/sdk";
+
+const msg = (role: Message["role"], content: string): Message => ({ role, content });
+
+// A turn's worth of entries: a user display message, the harness (LLM
+// transcript) messages for that turn, and the final assistant bubble.
+function turnEntries(): NewConversationEntry[] {
+  return [
+    { type: "user_message", id: "u1", message: msg("user", "hello"), turnId: "t1" },
+    { type: "harness_message", id: "h1", message: msg("user", "hello"), turnId: "t1" },
+    { type: "harness_message", id: "h2", message: msg("assistant", "hi there"), turnId: "t1" },
+    {
+      type: "assistant_message",
+      id: "a1",
+      message: msg("assistant", "hi there"),
+      turnId: "t1",
+      runId: "r1",
+    },
+  ];
+}
+
+describe("Phase 3c read cutover", () => {
+  const prevFlag = process.env.PONCHO_READ_ENTRIES;
+
+  afterEach(() => {
+    if (prevFlag === undefined) delete process.env.PONCHO_READ_ENTRIES;
+    else process.env.PONCHO_READ_ENTRIES = prevFlag;
+  });
+
+  it("get() rebuilds _harnessMessages/messages from entries when present", async () => {
+    delete process.env.PONCHO_READ_ENTRIES; // ON by default
+    const store = new InMemoryConversationStore();
+    const conv = await store.create("owner", "title", null);
+
+    // Seed the blob with stale messages so we can prove the override happened.
+    conv.messages = [msg("assistant", "STALE BLOB")];
+    conv._harnessMessages = [msg("assistant", "STALE BLOB HARNESS")];
+    await store.update(conv);
+
+    const entries = await store.appendEntries(conv.conversationId, "agent", null, turnEntries());
+
+    const loaded = await store.get(conv.conversationId);
+    expect(loaded).toBeDefined();
+    expect(loaded!._harnessMessages).toEqual(buildLlmContext(entries));
+    expect(loaded!.messages).toEqual(buildDisplaySnapshot(entries, 100000).messages);
+    // Display transcript drops the harness-only messages; keeps user + assistant bubble.
+    expect(loaded!.messages.map((m) => m.content)).toEqual(["hello", "hi there"]);
+  });
+
+  it("get() falls back to the blob when there are no entries", async () => {
+    delete process.env.PONCHO_READ_ENTRIES;
+    const store = new InMemoryConversationStore();
+    const conv = await store.create("owner", "title", null);
+    conv.messages = [msg("user", "blob only")];
+    conv._harnessMessages = [msg("user", "blob only harness")];
+    await store.update(conv);
+
+    const loaded = await store.get(conv.conversationId);
+    expect(loaded!.messages).toEqual([msg("user", "blob only")]);
+    expect(loaded!._harnessMessages).toEqual([msg("user", "blob only harness")]);
+  });
+
+  it("kill-switch PONCHO_READ_ENTRIES=0 reverts to blob reads even with entries", async () => {
+    process.env.PONCHO_READ_ENTRIES = "0";
+    const store = new InMemoryConversationStore();
+    const conv = await store.create("owner", "title", null);
+    conv.messages = [msg("user", "blob wins")];
+    await store.update(conv);
+    await store.appendEntries(conv.conversationId, "agent", null, turnEntries());
+
+    const loaded = await store.get(conv.conversationId);
+    expect(loaded!.messages).toEqual([msg("user", "blob wins")]);
+  });
+
+  it("get() does not mutate the stored blob conversation (clone)", async () => {
+    delete process.env.PONCHO_READ_ENTRIES;
+    const store = new InMemoryConversationStore();
+    const conv = await store.create("owner", "title", null);
+    conv.messages = [msg("assistant", "STALE BLOB")];
+    await store.update(conv);
+    await store.appendEntries(conv.conversationId, "agent", null, turnEntries());
+
+    await store.get(conv.conversationId);
+    // Re-read with the kill-switch on: should still see the untouched blob.
+    process.env.PONCHO_READ_ENTRIES = "0";
+    const blob = await store.get(conv.conversationId);
+    expect(blob!.messages).toEqual([msg("assistant", "STALE BLOB")]);
+  });
+});