From 04df7bf47fb38e6a36821f6db72c9da6a92e5ae3 Mon Sep 17 00:00:00 2001
From: liujing <a362165265@qq.com>
Date: Mon, 20 Jul 2026 20:51:37 +0800
Subject: [PATCH] fix: harden live workflow log streaming

---
 src/workflow-web-assets.ts |   66 +-
 src/workflow-web.test.ts   | 1498 +++++++++++++++++++++++++++++++++++-
 src/workflow-web.ts        |  103 ++-
 3 files changed, 1640 insertions(+), 27 deletions(-)

diff --git a/src/workflow-web-assets.ts b/src/workflow-web-assets.ts
index 3838e5a..669b7e2 100644
--- a/src/workflow-web-assets.ts
+++ b/src/workflow-web-assets.ts
@@ -1788,6 +1788,31 @@ export function getAssetsHtml(): string {
         if (container && parsed.length) {
           const frag = document.createDocumentFragment();
           parsed.forEach(entry => {
+            if (entry.type === 'progress') {
+              // Container already has a progress row from a newer page —
+              // skip older progress so we never overwrite newest values.
+              const containerRow = container.querySelector('[data-progress-key="progress"]');
+              if (containerRow) {
+                // The container row holds the most recent progress value;
+                // historical entries must not overwrite it.
+                return;
+              }
+              // No container row — check whether this batch already queued
+              // one (fragment rows are invisible to container.querySelector).
+              const fragRow = frag.querySelector('[data-progress-key="progress"]');
+              if (fragRow) {
+                // Update fragment-local row — entries arrive in file order
+                // so the last one is most recent.
+                const content = fragRow.querySelector('.item-content');
+                if (content) content.textContent = entry.content || entry.raw || '';
+                return;
+              }
+              // First progress entry we have seen — create a keyed row.
+              entry._progressKey = 'progress';
+              const row = buildTimelineRow(entry);
+              if (row) frag.appendChild(row);
+              return;
+            }
             const row = buildTimelineRow(entry);
             if (row) frag.appendChild(row);
           });
@@ -1899,18 +1924,30 @@ export function getAssetsHtml(): string {
       const container = document.getElementById('timeline-items-container');
       if (!container || !entries || !entries.length) return;
       const frag = document.createDocumentFragment();
+      // Track the most recent progress row in THIS batch so multiple progress
+      // entries arriving in one call still merge into one row.
+      let batchProgressRow = null;
       entries.forEach(entry => {
         // Merge high-frequency progress counters into one updatable row.
         if (entry.type === 'progress') {
           const key = 'progress';
           entry._progressKey = key;
-          const existing = container.querySelector('[data-progress-key="progress"]');
+          // Check batch-local row first (same call), then container (prior calls).
+          const existing = batchProgressRow || container.querySelector('[data-progress-key="progress"]');
           if (existing) {
             const content = existing.querySelector('.item-content');
             if (content) content.textContent = entry.content || entry.raw || '';
             timelineProgressRow = existing;
+            batchProgressRow = existing;
             return;
           }
+          // First progress in this batch – create the row.
+          const row = buildTimelineRow(entry);
+          if (row) {
+            batchProgressRow = row;
+            frag.appendChild(row);
+          }
+          return;
         }
         const row = buildTimelineRow(entry);
         if (row) frag.appendChild(row);
@@ -1945,13 +1982,30 @@ export function getAssetsHtml(): string {
       container.innerHTML = '';
       timelineProgressRow = null;
       const frag = document.createDocumentFragment();
+      // Merge high-frequency progress entries into a single updatable row
+      // (same logic as appendTimelineEntries).
+      let progressMerged = false;
       timelineEntries.forEach(entry => {
-        if (entry.type === 'progress') entry._progressKey = 'progress';
-        const row = buildTimelineRow(entry);
-        if (row) {
-          if (entry.type === 'progress') timelineProgressRow = row;
-          frag.appendChild(row);
+        if (entry.type === 'progress') {
+          if (!progressMerged) {
+            progressMerged = true;
+            entry._progressKey = 'progress';
+            const row = buildTimelineRow(entry);
+            if (row) {
+              timelineProgressRow = row;
+              frag.appendChild(row);
+            }
+          } else {
+            // Update the existing row's text instead of creating a new one.
+            if (timelineProgressRow) {
+              const contentEl = timelineProgressRow.querySelector('.item-content');
+              if (contentEl) contentEl.textContent = entry.content || entry.raw || '';
+            }
+          }
+          return;
         }
+        const row = buildTimelineRow(entry);
+        if (row) frag.appendChild(row);
       });
       container.appendChild(frag);
       timelineRenderedCount = timelineEntries.length;
diff --git a/src/workflow-web.test.ts b/src/workflow-web.test.ts
index 03a1377..42aef7b 100644
--- a/src/workflow-web.test.ts
+++ b/src/workflow-web.test.ts
@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import http from "node:http";
 import { Buffer } from "node:buffer";
-import { startWorkflowWebServer, splitCompleteUtf8, hasSymlinkInPath } from "./workflow-web.js";
+import { startWorkflowWebServer, splitCompleteUtf8, leadingIncompleteUtf8Bytes, readLogSlice, hasSymlinkInPath } from "./workflow-web.js";
 import { writeState, appendEvent, attemptLogPath, readState } from "./workflow-state.js";
 import type { WorkflowState } from "./workflow-types.js";
 
@@ -37,6 +37,7 @@ describe("workflow-web", () => {
   let tmpDir: string;
   let server: http.Server;
   let originalHome: string | undefined;
+  let savedAgentDir: string | undefined;
   let testHome: string;
   let port = 14319;
   let baseUrl = `http://127.0.0.1:${port}`;
@@ -47,6 +48,7 @@ describe("workflow-web", () => {
   beforeAll(async () => {
     // Setup temp workflows root directory
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-web-test-"));
+    savedAgentDir = process.env.AGENT_WORKFLOW_DIR;
     process.env.AGENT_WORKFLOW_DIR = tmpDir;
     originalHome = process.env.HOME;
     testHome = path.join(tmpDir, "home");
@@ -115,6 +117,8 @@ printf '%s\\n' '{"providers":[{"name":"test-provider","models":["test-model"]}]}
   afterAll(() => {
     return new Promise<void>((resolve) => {
       server.close(() => {
+        if (savedAgentDir === undefined) delete process.env.AGENT_WORKFLOW_DIR;
+        else process.env.AGENT_WORKFLOW_DIR = savedAgentDir;
         if (originalHome === undefined) delete process.env.HOME;
         else process.env.HOME = originalHome;
         fs.rmSync(tmpDir, { recursive: true, force: true });
@@ -435,7 +439,7 @@ printf '%s\\n' '{"providers":[{"name":"test-provider","models":["test-model"]}]}
       fetch: async () => ({ ok: true, json: async () => ({}), text: async () => "" }),
       EventSource: class { addEventListener() {} },
       setInterval: () => {},
-      console: { log: () => {}, error: () => {} },
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
     };
     vm.createContext(sandbox);
 
@@ -449,6 +453,1016 @@ printf '%s\\n' '{"providers":[{"name":"test-provider","models":["test-model"]}]}
     expect(typeof sandbox.resetRawLogs).toBe("function");
   });
 
+  it("progress entries merge into a single row via appendTimelineEntries", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    const el = (tag?: string) => {
+      const e: any = {
+        style: {},
+        classList: { add() {}, remove() {}, contains() { return false; } },
+        addEventListener() {},
+        setAttribute(k: string, v: any) { e[k] = v; },
+        getAttribute(k: string) { return e[k] || null; },
+        textContent: "",
+        value: "",
+        innerHTML: "",
+        disabled: false,
+        dataset: {} as any,
+        querySelector() { return null; },
+        appendChild(c: any) {
+          if (c && c.textContent) {
+            this.textContent += c.textContent;
+          }
+        },
+      };
+      return e;
+    };
+
+    const containerRows: any[] = [];
+    // Track individual rows appended via fragment
+    let allAppendedRows: any[] = [];
+    const container = {
+      innerHTML: "",
+      childNodes: [] as any[],
+      _rows: containerRows,
+      appendChild(child: any) {
+        // Unpack DocumentFragment children into rows
+        if (child && child._rows) {
+          for (const r of child._rows) {
+            this._rows.push(r);
+            allAppendedRows.push(r);
+          }
+        } else {
+          this._rows.push(child);
+          allAppendedRows.push(child);
+        }
+        this.childNodes.push(child);
+      },
+      querySelector(sel: string) {
+        if (sel === '[data-progress-key="progress"]') {
+          return allAppendedRows.find((r: any) => r.dataset && r.dataset.progressKey === "progress") || null;
+        }
+        return null;
+      },
+    };
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: (id: string) => {
+          if (id === "timeline-items-container") return container;
+          if (id === "load-more-timeline-btn") return el();
+          if (id === "load-more-raw-btn") return el();
+          if (id === "scroll-btn") return el();
+          if (id === "pending-live-badge") return { style: {}, textContent: "", onclick: null };
+          if (id === "timeline-view") return el();
+          if (id === "raw-view") return el();
+          return el();
+        },
+        querySelectorAll: () => ([]),
+        createElement: (tag: string) => el(tag),
+        addEventListener() {},
+        createDocumentFragment() {
+          const frag: any = { childNodes: [], _rows: [], appendChild(c: any) { this.childNodes.push(c); this._rows.push(c); } };
+          frag.querySelector = (sel) => {
+            if (sel === '[data-progress-key="progress"]') {
+              return frag._rows.find(r => r.dataset && r.dataset.progressKey === 'progress') || null;
+            }
+            return null;
+          };
+          return frag;
+        },
+        createTextNode: (t: string) => ({ textContent: t }),
+      },
+      fetch: async () => ({ ok: true, json: async () => ({}), text: async () => "" }),
+      EventSource: class { addEventListener() {} },
+      setInterval: () => {},
+      setTimeout: () => {},
+      TextEncoder: require("util").TextEncoder,
+      TextDecoder: require("util").TextDecoder,
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+    };
+
+    sandbox.coveredRanges = [];
+    vm.createContext(sandbox);
+    script.runInContext(sandbox);
+
+    sandbox.timelineEntries = [];
+    sandbox.timelineResidualState = { value: "" };
+    sandbox.timelineOlderHeadResidual = { value: "" };
+    sandbox.timelineProgressRow = null;
+    sandbox.activeRun = { executor: "claude" };
+
+    // Simulate sequential SSE events: each appendTimelineEntries call merges into
+    // the previously-rendered progress row.
+    sandbox.appendTimelineEntries([
+      { type: "progress", content: "token 100", raw: "", _progressKey: undefined },
+    ], false);
+    expect(containerRows.length).toBe(1);
+    const firstRow = containerRows[0];
+
+    sandbox.appendTimelineEntries([
+      { type: "progress", content: "token 200", raw: "", _progressKey: undefined },
+    ], false);
+    // Merge: no new row, same row updated
+    expect(containerRows.length).toBe(1);
+    // The row's dataset.progressKey should be set
+    expect(firstRow.dataset.progressKey).toBe("progress");
+
+    // Third call: still merges into same row
+    sandbox.appendTimelineEntries([
+      { type: "progress", content: "token 300", raw: "", _progressKey: undefined },
+    ], false);
+    expect(containerRows.length).toBe(1);
+  });
+
+  it("renderTimeline and appendTimelineEntries defined in generated script", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    expect(html).toContain("function renderTimeline");
+    expect(html).toContain("function appendTimelineEntries");
+    expect(html).toContain("progressMerged");
+    expect(html).toContain("function setupSSE");
+    expect(html).toContain("function returnToLive");
+  });
+
+  it("generated script runs without syntax error in sandbox", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    const el = () => ({
+      style: {},
+      classList: { add() {}, remove() {}, contains() { return false; } },
+      addEventListener() {},
+      setAttribute() {},
+      getAttribute() { return null; },
+      textContent: "",
+      value: "",
+      innerHTML: "",
+      disabled: false,
+      appendChild() {},
+      querySelector() { return null; },
+    });
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: () => el(),
+        querySelectorAll: () => ([]),
+        createElement: () => el(),
+        addEventListener() {},
+        createDocumentFragment() {
+          return { childNodes: [], appendChild() {} };
+        },
+      },
+      fetch: async () => ({ ok: true, json: async () => ({}), text: async () => "" }),
+      EventSource: class { addEventListener() {} },
+      setInterval: () => {},
+      setTimeout: () => {},
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+    };
+    vm.createContext(sandbox);
+    expect(() => script.runInContext(sandbox)).not.toThrow();
+  });
+
+  it("appendTimelineEntries merges multiple progress entries in one call", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    // Container that tracks appended rows via fragment unpacking
+    const allRows: any[] = [];
+    const container = {
+      innerHTML: "",
+      _rows: allRows,
+      appendChild(child: any) {
+        // Unpack fragment children into _rows
+        const children = child && child._rows ? child._rows : [child];
+        for (const r of children) { this._rows.push(r); }
+      },
+      querySelector(sel: string) {
+        if (sel === '[data-progress-key="progress"]') {
+          return this._rows.find((r: any) => r.dataset && r.dataset.progressKey === "progress") || null;
+        }
+        return null;
+      },
+    };
+
+    const el = (tag?: string) => {
+      const e: any = {
+        style: {}, classList: { add() {}, remove() {}, contains() { return false; } },
+        addEventListener() {}, setAttribute(k: string, v: any) { e[k] = v; },
+        getAttribute(k: string) { return e[k] || null; },
+        textContent: "", value: "", innerHTML: "", disabled: false,
+        dataset: {} as any,
+        _contentSpan: null as any,
+        appendChild(c: any) {
+          if (c && c.className === 'item-content') e._contentSpan = c;
+          if (c && typeof c.textContent === 'string') {
+            e.textContent += c.textContent;
+          }
+        },
+        querySelector(sel: string) {
+          if (sel === '.item-content') return e._contentSpan;
+          return null;
+        },
+      };
+      return e;
+    };
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: (id: string) => {
+          if (id === "timeline-items-container") return container;
+          if (id === "load-more-timeline-btn") return { style: {} };
+          if (id === "load-more-raw-btn") return { style: {} };
+          if (id === "scroll-btn") return el();
+          if (id === "pending-live-badge") return el();
+          if (id === "timeline-view") return el();
+          if (id === "raw-view") return el();
+          return el();
+        },
+        querySelectorAll: () => ([]),
+        createElement: (tag: string) => el(),
+        addEventListener() {},
+        createDocumentFragment() {
+          const frag: any = { childNodes: [], _rows: [], appendChild(c: any) { this.childNodes.push(c); this._rows.push(c); } };
+          frag.querySelector = (sel) => {
+            if (sel === '[data-progress-key="progress"]') {
+              return frag._rows.find(r => r.dataset && r.dataset.progressKey === 'progress') || null;
+            }
+            return null;
+          };
+          return frag;
+        },
+        createTextNode: (t: string) => ({ textContent: t }),
+      },
+      fetch: async () => ({ ok: true, json: async () => ({}), text: async () => "" }),
+      EventSource: class { addEventListener() {} },
+      setInterval: () => {}, setTimeout: () => {},
+      TextEncoder: require("util").TextEncoder,
+      TextDecoder: require("util").TextDecoder,
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+    };
+
+    sandbox.coveredRanges = [];
+    sandbox.currentLogView = "timeline";
+    sandbox.activeRun = { executor: "claude" };
+    sandbox.timelineEntries = [];
+
+    vm.createContext(sandbox);
+    script.runInContext(sandbox);
+
+    sandbox.timelineResidualState = { value: "" };
+    sandbox.timelineOlderHeadResidual = { value: "" };
+    sandbox.timelineProgressRow = null;
+
+    // Five progress entries in a single batch → must produce only ONE row
+    sandbox.appendTimelineEntries([
+      { type: "progress", content: "token 100", raw: "", _progressKey: undefined },
+      { type: "progress", content: "token 200", raw: "", _progressKey: undefined },
+      { type: "progress", content: "token 300", raw: "", _progressKey: undefined },
+      { type: "progress", content: "token 400", raw: "", _progressKey: undefined },
+      { type: "progress", content: "token 500", raw: "", _progressKey: undefined },
+    ], false);
+
+    expect(allRows.length).toBe(1);
+    expect(allRows[0].dataset.progressKey).toBe("progress");
+    // The row should contain the LAST progress entry's text (via live DOM)
+    const contentSpan = allRows[0].querySelector('.item-content');
+    expect(contentSpan).not.toBeNull();
+    expect(contentSpan!.textContent).toContain("500");
+
+    // Interleave progress with non-progress entries in one call
+    allRows.length = 0;
+    sandbox.timelineEntries = [];
+
+    sandbox.appendTimelineEntries([
+      { type: "raw", content: "before", raw: "before" },
+      { type: "progress", content: "p1", raw: "", _progressKey: undefined },
+      { type: "text", content: "middle", raw: "middle" },
+      { type: "progress", content: "p2", raw: "", _progressKey: undefined },
+      { type: "raw", content: "after", raw: "after" },
+    ], false);
+
+    // Should have 4 rows: raw, progress (once), text, raw
+    expect(allRows.length).toBe(4);
+    // First row is "raw" (before) – badge label + content = "原始before"
+    expect(allRows[0].textContent).toContain("before");
+    // Second row is the single merged progress ("p2" is the last)
+    expect(allRows[1].dataset.progressKey).toBe("progress");
+    const contentSpan2 = allRows[1].querySelector('.item-content');
+    expect(contentSpan2).not.toBeNull();
+    expect(contentSpan2!.textContent).toContain("p2");
+    // Third row is "text" (middle) – badge label + content
+    expect(allRows[2].textContent).toContain("middle");
+    // Fourth row is "raw" (after)
+    expect(allRows[3].textContent).toContain("after");
+  });
+
+  it("SSE applyLiveLogPayload: dedup, partial-overlap, gap-fetch, different-cycle via vm.runInContext", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    // Track fetch calls for gap verification
+    let fetchCalls = 0;
+    // EventSource listener registry for cycle-follow tests
+    const esListeners: Record<string, Function> = {};
+
+    const el = () => ({
+      style: {}, classList: { add() {}, remove() {}, contains() { return false; } },
+      addEventListener() {}, setAttribute() {}, getAttribute() { return null; },
+      textContent: "", value: "", innerHTML: "", disabled: false,
+      dataset: {} as any, appendChild() {}, querySelector() { return null; },
+    });
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: (id: string) => {
+          if (id === "pending-live-badge") return { style: {}, textContent: "", onclick: null };
+          if (id === "follow-live-btn") return { className: "", textContent: "" };
+          if (id === "scroll-btn") return { className: "", textContent: "" };
+          if (id === "timeline-items-container") return el();
+          if (id === "timeline-view") return el();
+          if (id === "raw-view") return el();
+          if (id === "load-more-timeline-btn") return { style: {}, textContent: "" };
+          if (id === "load-more-raw-btn") return { style: {}, textContent: "" };
+          return el();
+        },
+        querySelectorAll: () => ([]),
+        createElement: (tag: string) => el(),
+        addEventListener() {},
+        createDocumentFragment() {
+          const frag: any = { childNodes: [], appendChild() {} };
+          return frag;
+        },
+        createTextNode: (t: string) => ({ textContent: t }),
+      },
+      fetch: async (url: string) => {
+        fetchCalls++;
+        if (url.includes("offset=")) {
+          const u = new URL(url, "http://localhost");
+          const offset = parseInt(u.searchParams.get("offset") || "0", 10);
+          const limit = parseInt(u.searchParams.get("limit") || "0", 10);
+          return {
+            ok: true,
+            json: async () => ({
+              content: "GAP",
+              startOffset: offset,
+              endOffset: offset + limit,
+              nextOffset: offset + limit,
+              hasMore: false,
+              hasMoreBefore: false,
+              size: 10000,
+            }),
+          };
+        }
+        return { ok: true, json: async () => ({}), text: async () => "" };
+      },
+      EventSource: class {
+        constructor(_url: string) {}
+        addEventListener(event: string, handler: Function) {
+          esListeners[event] = handler;
+        }
+        close() {}
+      },
+      setInterval: () => ({} as any),
+      setTimeout: () => ({} as any),
+      clearInterval: () => {},
+      clearTimeout: () => {},
+      TextEncoder: require("util").TextEncoder,
+      TextDecoder: require("util").TextDecoder,
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+      URL,
+    };
+
+    sandbox.coveredRanges = [];
+    sandbox.currentLogView = "timeline";
+    sandbox.selectedCycle = 1;
+    sandbox.selectedAttempt = 0;
+    sandbox.selectedLogFile = "exec";
+
+    vm.createContext(sandbox);
+    script.runInContext(sandbox);
+
+    // Set all let-bound globals via runInContext so the script's internal
+    // bindings are updated, not just the sandbox properties.
+    const ctxSet = (name: string, val: any) => {
+      const json = JSON.stringify(val);
+      vm.runInContext(`${name} = ${json}`, sandbox);
+    };
+    ctxSet("activeRun", { executor: "claude", runId: "test-run", currentCycle: 1, cycles: [], status: "executing" });
+    ctxSet("followLive", true);
+    ctxSet("autoScroll", true);
+    ctxSet("selectedAttempt", 0);
+    ctxSet("pendingLiveCount", 0);
+    // Set runs as a simple array so setupSSE's state handler can call findIndex
+    vm.runInContext("runs = [{ runId: 'test-run', status: 'executing' }]", sandbox);
+    ctxSet("selectedCycle", 1);
+    ctxSet("selectedAttempt", 0);
+
+    sandbox.timelineResidualState = { value: "" };
+    sandbox.timelineOlderHeadResidual = { value: "" };
+
+    // Helper: read internal let variables
+    const readVar = (name: string) => vm.runInContext(name, sandbox);
+
+    // ========== 1. Dedup: fully covered payload ==========
+    sandbox.markSeen(100, 200);
+    const fcBefore = fetchCalls;
+    await sandbox.applyLiveLogPayload({
+      cycleIndex: 1, attemptIndex: 0, fileType: "exec",
+      startOffset: 150, endOffset: 180,
+      content: "overlap",
+    });
+    expect(fetchCalls).toBe(fcBefore);
+
+    // ========== 2. Partial overlap extends timelineEndOffset ==========
+    await sandbox.applyLiveLogPayload({
+      cycleIndex: 1, attemptIndex: 0, fileType: "exec",
+      startOffset: 180, endOffset: 220,
+      content: "partial overlap",
+    });
+    const endOff1 = readVar("timelineEndOffset");
+    expect(endOff1).toBeGreaterThanOrEqual(200);
+
+    // ========== 3. Gap between cursor and payload triggers fetch ==========
+    const fcBeforeGap = fetchCalls;
+    await sandbox.applyLiveLogPayload({
+      cycleIndex: 1, attemptIndex: 0, fileType: "exec",
+      startOffset: 400, endOffset: 450,
+      content: "gap payload",
+    });
+    expect(fetchCalls).toBeGreaterThan(fcBeforeGap);
+    const endOff2 = readVar("timelineEndOffset");
+    expect(endOff2).toBeGreaterThanOrEqual(400);
+
+    // ========== 4. Different cycle + scrolled up: pendingLiveCount increments ==========
+    ctxSet("autoScroll", false);
+    await sandbox.applyLiveLogPayload({
+      cycleIndex: 2, attemptIndex: 0, fileType: "exec",
+      startOffset: 50, endOffset: 100,
+      content: "different cycle while scrolled up",
+    });
+    const plc1 = readVar("pendingLiveCount");
+    expect(plc1).toBeGreaterThan(0);
+
+    // ========== 5. Different cycle + following live: pendingLiveCount unchanged ==========
+    ctxSet("autoScroll", true);
+    await sandbox.applyLiveLogPayload({
+      cycleIndex: 3, attemptIndex: 0, fileType: "exec",
+      startOffset: 10, endOffset: 50,
+      content: "following live",
+    });
+    const plc2 = readVar("pendingLiveCount");
+    expect(plc2).toBe(plc1);
+
+    // ========== 6. Cycle following via EventSource state event ==========
+    // Directly register a state handler (like setupSSE does) to test cycle following
+    esListeners["state"] = (e: any) => {
+      const updatedState = JSON.parse(e.data);
+      const prevCycle = readVar("activeRun") ? readVar("activeRun").currentCycle : null;
+      vm.runInContext("activeRun = " + e.data, sandbox);
+      // Simulate what the real state handler does: follow live cycle
+      const fl = readVar("followLive");
+      if (fl) {
+        vm.runInContext("selectedCycle = activeRun.currentCycle || 1", sandbox);
+      }
+    };
+    expect(typeof esListeners["state"]).toBe("function");
+    const newState = JSON.parse(JSON.stringify(readVar("activeRun")));
+    newState.currentCycle = 5;
+    esListeners["state"]({ data: JSON.stringify(newState) });
+    const updatedCycle = readVar("selectedCycle");
+    expect(updatedCycle).toBe(5);
+  });
+
+  it("loadOlderTimeline merges multiple progress records into one keyed row", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    // Container that tracks rows via fragment unpacking
+    const allRows: any[] = [];
+    const container = {
+      innerHTML: "",
+      _rows: allRows,
+      childNodes: [] as any[],
+      parentElement: { scrollTop: 0, scrollHeight: 0 },
+      insertBefore(child: any, _ref: any) {
+        const children = child && child._rows ? child._rows : [child];
+        for (const r of children) { this._rows.push(r); this.childNodes.push(r); }
+      },
+      appendChild(child: any) {
+        const children = child && child._rows ? child._rows : [child];
+        for (const r of children) { this._rows.push(r); this.childNodes.push(r); }
+      },
+      querySelector(sel: string) {
+        if (sel === '[data-progress-key="progress"]') {
+          return this._rows.find((r: any) => r.dataset && r.dataset.progressKey === "progress") || null;
+        }
+        return null;
+      },
+      getElementsByClassName() { return []; },
+    };
+
+    const el = (tag?: string) => {
+      const e: any = {
+        style: {}, classList: { add() {}, remove() {}, contains() { return false; } },
+        addEventListener() {}, setAttribute(k: string, v: any) { e[k] = v; },
+        getAttribute(k: string) { return e[k] || null; },
+        textContent: "", value: "", innerHTML: "", disabled: false,
+        dataset: {} as any, _rows: [] as any[],
+        _contentSpan: null as any,
+        appendChild(c: any) {
+          if (c && c.className === 'item-content') e._contentSpan = c;
+          if (c && typeof c.textContent === 'string') {
+            e.textContent += c.textContent;
+          }
+          e._rows.push(c);
+        },
+        querySelector(sel: string) {
+          if (sel === '.item-content') return e._contentSpan;
+          return null;
+        },
+      };
+      return e;
+    };
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: (id: string) => {
+          if (id === "timeline-items-container") return container;
+          if (id === "load-more-timeline-btn") return { style: {}, textContent: "" };
+          if (id === "load-more-raw-btn") return { style: {}, textContent: "" };
+          if (id === "scroll-btn") return { className: "", textContent: "" };
+          if (id === "pending-live-badge") return el();
+          if (id === "timeline-view") return el();
+          if (id === "raw-view") return el();
+          return el();
+        },
+        querySelectorAll: () => ([]),
+        createElement: (tag: string) => el(),
+        addEventListener() {},
+        createDocumentFragment() {
+          const frag: any = { childNodes: [], _rows: [], appendChild(c: any) { this.childNodes.push(c); this._rows.push(c); } };
+          frag.querySelector = (sel) => {
+            if (sel === '[data-progress-key="progress"]') {
+              return frag._rows.find(r => r.dataset && r.dataset.progressKey === 'progress') || null;
+            }
+            return null;
+          };
+          return frag;
+        },
+        createTextNode: (t: string) => ({ textContent: t }),
+      },
+      fetch: async () => ({
+        ok: true,
+        json: async () => ({
+          content: "line before\n{\"type\":\"progress\",\"message\":\"old p1\"}\n{\"type\":\"progress\",\"message\":\"old p2\"}\n{\"type\":\"raw\",\"content\":\"after\"}\n",
+          startOffset: 0,
+          endOffset: 200,
+          nextOffset: 200,
+          hasMoreBefore: false,
+          size: 200,
+        }),
+      }),
+      EventSource: class { addEventListener() {} close() {} },
+      setInterval: () => ({} as any),
+      setTimeout: () => ({} as any),
+      clearInterval: () => {},
+      clearTimeout: () => {},
+      TextEncoder: require("util").TextEncoder,
+      TextDecoder: require("util").TextDecoder,
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+    };
+
+    sandbox.coveredRanges = [];
+    sandbox.currentLogView = "timeline";
+    sandbox.selectedCycle = 1;
+    sandbox.selectedAttempt = 0;
+    sandbox.selectedLogFile = "exec";
+
+    vm.createContext(sandbox);
+    script.runInContext(sandbox);
+
+    // Set let-bound globals via runInContext
+    const ctxSet = (name: string, val: any) => {
+      const json = JSON.stringify(val);
+      vm.runInContext(`${name} = ${json}`, sandbox);
+    };
+    ctxSet("activeRun", { executor: "claude", runId: "test-run", currentCycle: 1 });
+    ctxSet("followLive", true);
+    ctxSet("autoScroll", true);
+    ctxSet("selectedCycle", 1);
+    ctxSet("selectedAttempt", 0);
+    ctxSet("timelineHasMoreBefore", true);
+    ctxSet("timelineStartOffset", 10);
+    ctxSet("viewGeneration", 42);
+    ctxSet("timelineEntries", [] as any[]);
+    ctxSet("runs", [{ runId: "test-run" }]);
+
+    sandbox.timelineResidualState = { value: "" };
+    sandbox.timelineOlderHeadResidual = { value: "" };
+
+    // Call loadOlderTimeline — it will fetch mock data and prepend rows
+    await sandbox.loadOlderTimeline();
+
+    // Should have: raw ("line before") + progress (merged "old p2") + raw ("after") = 3 rows
+    expect(allRows.length).toBe(3);
+    // The progress row must have dataset.progressKey set
+    const progressRow = allRows.find((r: any) => r.dataset && r.dataset.progressKey === "progress");
+    expect(progressRow).toBeTruthy();
+    // The progress row must contain the NEWEST progress value ("old p2")
+    const contentSpan = progressRow!.querySelector('.item-content');
+    expect(contentSpan).toBeTruthy();
+    expect(contentSpan!.textContent).toContain("old p2");
+    // Non-progress rows preserved
+    expect(allRows[0].textContent).toContain("line before");
+    expect(allRows[2].textContent).toContain("after");
+  });
+
+  it("loadOlderTimeline when newer progress row exists: container row preserved", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    const allRows: any[] = [];
+    const container = {
+      innerHTML: "", _rows: allRows, childNodes: [] as any[],
+      parentElement: { scrollTop: 0, scrollHeight: 0 },
+      insertBefore(child: any, _ref: any) {
+        const children = child && child._rows ? child._rows : [child];
+        for (const r of children) { this._rows.push(r); this.childNodes.push(r); }
+      },
+      appendChild(child: any) {
+        const children = child && child._rows ? child._rows : [child];
+        for (const r of children) { this._rows.push(r); this.childNodes.push(r); }
+      },
+      querySelector(sel: string) {
+        if (sel === '[data-progress-key="progress"]') {
+          return this._rows.find((r: any) => r.dataset && r.dataset.progressKey === "progress") || null;
+        }
+        return null;
+      },
+      getElementsByClassName() { return []; },
+    };
+
+    const el = (tag?: string) => {
+      const e: any = {
+        style: {}, classList: { add() {}, remove() {}, contains() { return false; } },
+        addEventListener() {}, setAttribute(k: string, v: any) { e[k] = v; },
+        getAttribute(k: string) { return e[k] || null; },
+        textContent: "", value: "", innerHTML: "", disabled: false,
+        dataset: {} as any, _rows: [] as any[],
+        _contentSpan: null as any,
+        appendChild(c: any) {
+          if (c && c.className === 'item-content') e._contentSpan = c;
+          if (c && typeof c.textContent === 'string') {
+            e.textContent += c.textContent;
+          }
+          e._rows.push(c);
+        },
+        querySelector(sel: string) {
+          if (sel === '.item-content') return e._contentSpan;
+          return null;
+        },
+      };
+      return e;
+    };
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: (id: string) => {
+          if (id === "timeline-items-container") return container;
+          if (id === "load-more-timeline-btn") return { style: {}, textContent: "" };
+          if (id === "load-more-raw-btn") return { style: {}, textContent: "" };
+          if (id === "scroll-btn") return { className: "", textContent: "" };
+          if (id === "pending-live-badge") return el();
+          if (id === "timeline-view") return el();
+          if (id === "raw-view") return el();
+          return el();
+        },
+        querySelectorAll: () => ([]),
+        createElement: (tag: string) => el(),
+        addEventListener() {},
+        createDocumentFragment() {
+          const frag: any = { childNodes: [], _rows: [], appendChild(c: any) { this.childNodes.push(c); this._rows.push(c); } };
+          frag.querySelector = (sel) => {
+            if (sel === '[data-progress-key="progress"]') {
+              return frag._rows.find(r => r.dataset && r.dataset.progressKey === 'progress') || null;
+            }
+            return null;
+          };
+          return frag;
+        },
+        createTextNode: (t: string) => ({ textContent: t }),
+      },
+      fetch: async () => ({
+        ok: true,
+        json: async () => ({
+          content: "older line\n",
+          startOffset: 0,
+          endOffset: 100,
+          nextOffset: 100,
+          hasMoreBefore: false,
+          size: 200,
+        }),
+      }),
+      EventSource: class { addEventListener() {} close() {} },
+      setInterval: () => ({} as any),
+      setTimeout: () => ({} as any),
+      clearInterval: () => {},
+      clearTimeout: () => {},
+      TextEncoder: require("util").TextEncoder,
+      TextDecoder: require("util").TextDecoder,
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+    };
+
+    sandbox.coveredRanges = [];
+    sandbox.currentLogView = "timeline";
+
+    vm.createContext(sandbox);
+    script.runInContext(sandbox);
+
+    const ctxSet = (name: string, val: any) => {
+      const json = JSON.stringify(val);
+      vm.runInContext(`${name} = ${json}`, sandbox);
+    };
+    ctxSet("activeRun", { executor: "claude", runId: "test-run", currentCycle: 1 });
+    ctxSet("followLive", true);
+    ctxSet("autoScroll", true);
+    ctxSet("selectedCycle", 1);
+    ctxSet("selectedAttempt", 0);
+    ctxSet("timelineHasMoreBefore", true);
+    ctxSet("timelineStartOffset", 10);
+    ctxSet("viewGeneration", 99);
+    ctxSet("timelineEntries", [] as any[]);
+    ctxSet("runs", [{ runId: "test-run" }]);
+
+    sandbox.timelineResidualState = { value: "" };
+    sandbox.timelineOlderHeadResidual = { value: "" };
+
+    // Pre-populate a newer progress row in the container
+    const newerProgressEl = el();
+    newerProgressEl.dataset.progressKey = "progress";
+    newerProgressEl.textContent = "newer value";
+    allRows.push(newerProgressEl);
+
+    await sandbox.loadOlderTimeline();
+
+    // The newer progress row must be unchanged (not overwritten by older data)
+    const progressRow = container.querySelector('[data-progress-key="progress"]');
+    expect(progressRow).toBeTruthy();
+    expect(progressRow!.textContent).toContain("newer value");
+    // The older non-progress row should still be prepended
+    expect(allRows.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("cycle following via production setupSSE state listener", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    const scriptContent = scriptMatch![1];
+    const vm = require("node:vm");
+    const script = new vm.Script(scriptContent);
+
+    // Track EventSource listeners registered by production code
+    const esListeners: Record<string, Function> = {};
+
+    const el = () => ({
+      style: {}, classList: { add() {}, remove() {}, contains() { return false; } },
+      addEventListener() {}, setAttribute() {}, getAttribute() { return null; },
+      textContent: "", value: "", innerHTML: "", disabled: false,
+      dataset: {} as any, appendChild() {}, querySelector() { return null; },
+    });
+
+    const sandbox: any = {
+      window: {},
+      document: {
+        getElementById: (id: string) => {
+          // Elements used by populateCyclesDropdown, onCycleOrAttemptUIChange, etc.
+          if (id === "cycle-select") return { innerHTML: "", value: "", appendChild() {} };
+          if (id === "attempt-select") return { innerHTML: "", value: "", appendChild() {} };
+          if (id === "log-file-select") return { value: "" };
+          if (id === "agy-file-group") return { style: { display: "" } };
+          if (id === "pending-live-badge") return { style: {}, textContent: "", onclick: null };
+          if (id === "follow-live-btn") return { className: "", textContent: "" };
+          if (id === "scroll-btn") return { className: "", textContent: "" };
+          if (id === "view-status-badge") return { textContent: "", style: {} };
+          if (id === "view-current-cycle") return { textContent: "" };
+          if (id === "view-updated-at") return { textContent: "" };
+          if (id === "timeline-view") return { scrollTop: 0, scrollHeight: 0, addEventListener() {} };
+          if (id === "raw-view") return { scrollTop: 0, scrollHeight: 0, addEventListener() {} };
+          if (id === "timeline-items-container") {
+            return { innerHTML: "", appendChild() {}, querySelector() { return null; }, getElementsByClassName() { return []; } };
+          }
+          if (id === "load-more-timeline-btn") return { style: {}, textContent: "" };
+          if (id === "load-more-raw-btn") return { style: {}, textContent: "" };
+          return el();
+        },
+        querySelectorAll: () => ([]),
+        createElement: (tag: string) => el(),
+        addEventListener() {},
+        createDocumentFragment() {
+          return { childNodes: [], appendChild() {} };
+        },
+        createTextNode: (t: string) => ({ textContent: t }),
+      },
+      fetch: async () => ({ ok: true, json: async () => ({ content: "", startOffset: 0, endOffset: 0, size: 0 }) }),
+      EventSource: class {
+        constructor(_url: string) {}
+        addEventListener(event: string, handler: Function) { esListeners[event] = handler; }
+        close() {}
+      },
+      setInterval: () => ({} as any),
+      setTimeout: () => ({} as any),
+      clearInterval: () => {},
+      clearTimeout: () => {},
+      TextEncoder: require("util").TextEncoder,
+      TextDecoder: require("util").TextDecoder,
+      console: { log: (...args: any[]) => {}, error: (...args: any[]) => console.log("ERR:", ...args.map((a: any) => a?.message || a)) },
+    };
+
+    sandbox.coveredRanges = [];
+    sandbox.currentLogView = "raw";
+    sandbox.selectedCycle = 1;
+    sandbox.selectedAttempt = 0;
+    sandbox.selectedLogFile = "exec";
+
+    vm.createContext(sandbox);
+    script.runInContext(sandbox);
+
+    const ctxSet = (name: string, val: any) => {
+      const json = JSON.stringify(val);
+      vm.runInContext(`${name} = ${json}`, sandbox);
+    };
+    const readVar = (name: string) => vm.runInContext(name, sandbox);
+
+    // Set up initial state that setupSSE needs
+    ctxSet("activeRun", {
+      runId: "test-run", executor: "claude", status: "executing",
+      currentCycle: 1, maxCycles: 5, updatedAt: new Date().toISOString(),
+      cycles: [{ cycleIndex: 1, startedAt: new Date().toISOString(), executorAttemptLogs: ["cycle-1-exec.log"] }],
+      plan: { title: "" },
+      createdAt: new Date().toISOString(),
+    });
+    ctxSet("followLive", true);
+    ctxSet("autoScroll", true);
+    ctxSet("selectedCycle", 1);
+    ctxSet("selectedAttempt", 0);
+    ctxSet("pendingLiveCount", 0);
+    ctxSet("runs", [{ runId: "test-run" }]);
+
+    // Call production setupSSE — registers real EventSource listeners
+    sandbox.setupSSE("test-run");
+
+    // The production code must have registered a 'state' listener
+    expect(typeof esListeners["state"]).toBe("function");
+
+    // Build a cycle-changing state payload
+    const newState = {
+      runId: "test-run", executor: "claude", status: "executing",
+      currentCycle: 3, maxCycles: 5, updatedAt: new Date().toISOString(),
+      cycles: [{ cycleIndex: 3, startedAt: new Date().toISOString(), executorAttemptLogs: ["cycle-3-exec.log"] }],
+      plan: { title: "" },
+      createdAt: new Date().toISOString(),
+    };
+
+    // Invoke the production state listener
+    esListeners["state"]({ data: JSON.stringify(newState) });
+
+    // selectedCycle must follow the new cycle
+    expect(readVar("selectedCycle")).toBe(3);
+    // selectedAttempt must reflect the new cycle's last attempt
+    expect(readVar("selectedAttempt")).toBe(0);
+    // activeRun must be updated
+    const ar = readVar("activeRun");
+    expect(ar.currentCycle).toBe(3);
+  });
+
+  describe("API coverage continuity for tail+before pagination", () => {
+    let tmpDir: string;
+    let server: http.Server;
+    let port = 14322;
+    let baseUrl: string;
+    let hash = "coverage-hash";
+    let runId = "coverage-run";
+    let savedAgentDir: string | undefined;
+
+    beforeAll(async () => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-api-coverage-"));
+      savedAgentDir = process.env.AGENT_WORKFLOW_DIR;
+      process.env.AGENT_WORKFLOW_DIR = tmpDir;
+
+      const runDir = path.join(tmpDir, hash, runId);
+      fs.mkdirSync(runDir, { recursive: true });
+
+      const mockState: WorkflowState = {
+        version: "1", runId, repoHash: hash, repoRoot: "/tmp",
+        executor: "claude", status: "executing", maxCycles: 5, currentCycle: 1,
+        cycles: [{ cycleIndex: 1, startedAt: new Date().toISOString(), executorAttemptLogs: ["cycle-1-exec.log"] }],
+        plan: { version: "1", title: "Coverage Test", planMarkdown: "", scope: [], acceptanceCriteria: [], verificationCommands: [] },
+        createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+      };
+      writeState(runDir, mockState);
+
+      const logPath = attemptLogPath(runDir, 1, 0);
+      fs.writeFileSync(logPath, "", "utf8");
+
+      server = await startWorkflowWebServer(port);
+      baseUrl = `http://127.0.0.1:${port}`;
+    });
+
+    afterAll(() => {
+      return new Promise<void>((resolve) => {
+        server.close(() => {
+          if (savedAgentDir === undefined) delete process.env.AGENT_WORKFLOW_DIR;
+          else process.env.AGENT_WORKFLOW_DIR = savedAgentDir;
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+          resolve();
+        });
+      });
+    });
+
+    it("tail then continuous before pagination covers every byte exactly once", async () => {
+      const runDir = path.join(tmpDir, hash, runId);
+      const logPath = attemptLogPath(runDir, 1, 0);
+
+      // Write a file with mixed content
+      const lines: string[] = [];
+      for (let i = 0; i < 50; i++) {
+        lines.push(`log entry ${i.toString().padStart(3, "0")}: 你好世界🚀\n`);
+      }
+      const content = lines.join("");
+      fs.writeFileSync(logPath, content, "utf8");
+      const fileSize = fs.statSync(logPath).size;
+
+      // Tail load
+      const tailRes = await fetch(`${baseUrl}/api/runs/${runId}/logs?cycle=1&attempt=0&tail=1&limit=500`);
+      const tail = await tailRes.json();
+      expect(tail.hasMoreBefore).toBe(true);
+
+      // Sequential before loads
+      const pages = [tail];
+      let before = tail.startOffset;
+      let guard = 0;
+      while (before > 0 && guard++ < 20) {
+        const res = await fetch(`${baseUrl}/api/runs/${runId}/logs?cycle=1&attempt=0&before=${before}&limit=500`);
+        const data = await res.json();
+        pages.push(data);
+        before = data.startOffset;
+        if (!data.hasMoreBefore) break;
+      }
+
+      // Verify coverage chain: each page's endOffset === next page's startOffset
+      for (let i = pages.length - 1; i > 0; i--) {
+        expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+      }
+
+      // First page starts at 0, last ends at file size
+      expect(pages[pages.length - 1].startOffset).toBe(0);
+      expect(pages[pages.length - 1].hasMoreBefore).toBe(false);
+      expect(pages[0].endOffset).toBe(fileSize);
+
+      // Total byte coverage equals file size
+      const totalCovered = pages.reduce((sum: number, p: any) => sum + (p.endOffset - p.startOffset), 0);
+      expect(totalCovered).toBe(fileSize);
+
+      // Concatenated content reconstructs original
+      const concatenated = pages.map((p: any) => p.content).reverse().join("");
+      // Allow small tolerance for replacement chars at boundaries (2-3 chars max)
+      const diff = Buffer.byteLength(concatenated, "utf8") - fileSize;
+      expect(Math.abs(diff)).toBeLessThanOrEqual(3);
+    });
+  });
+
   // symlinks containment tests (Finding codex-4-4)
   it("rejects symlinks in run listing and direct requests", async () => {
     // 1. Create a symlinked hash directory
@@ -534,7 +1548,7 @@ printf '%s\\n' '{"providers":[{"name":"test-provider","models":["test-model"]}]}
       });
       req.end();
     });
-  });
+  }, 15_000);
 
   it("closes SSE connection when state transitions to non-executing status", async () => {
     const runDir = path.join(tmpDir, hash, runId);
@@ -588,9 +1602,11 @@ describe("UTF-8 boundary and EOF API progression", () => {
   let tmpDir: string;
   let server: http.Server;
   let baseUrl: string;
+  let savedAgentDir: string | undefined;
 
   beforeAll(async () => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-web-utf8-"));
+    savedAgentDir = process.env.AGENT_WORKFLOW_DIR;
     process.env.AGENT_WORKFLOW_DIR = tmpDir;
 
     const runId = "utf8-run";
@@ -619,6 +1635,8 @@ describe("UTF-8 boundary and EOF API progression", () => {
   afterAll(() => {
     return new Promise<void>((resolve) => {
       server.close(() => {
+        if (savedAgentDir === undefined) delete process.env.AGENT_WORKFLOW_DIR;
+        else process.env.AGENT_WORKFLOW_DIR = savedAgentDir;
         fs.rmSync(tmpDir, { recursive: true, force: true });
         resolve();
       });
@@ -658,3 +1676,477 @@ describe("hasSymlinkInPath", () => {
     fs.rmSync(tempRoot, { recursive: true, force: true });
   });
 });
+
+describe("readLogSlice before pagination UTF-8 boundary continuity", () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-before-utf8-"));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns continuous byte ranges across before-pages with 3-byte UTF-8 characters", () => {
+    const chars = "中".repeat(20); // 60 bytes total
+    const filePath = path.join(tmpDir, "chinese.log");
+    fs.writeFileSync(filePath, chars, "utf8");
+    const size = Buffer.byteLength(chars, "utf8");
+
+    let before = size;
+    const pages: Array<{ content: string; startOffset: number; endOffset: number }> = [];
+    for (let i = 0; i < 10; i++) {
+      const r = readLogSlice(filePath, { before, limit: 10 });
+      if (r.content.length === 0) break;
+      pages.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) break;
+    }
+
+    // Verify continuous coverage: each page's endOffset === next page's startOffset
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    // First page must start at byte 0 (file start)
+    expect(pages[pages.length - 1].startOffset).toBe(0);
+    expect(pages[pages.length - 1].hasMoreBefore).toBe(false);
+
+    // Last page must end at file size
+    expect(pages[0].endOffset).toBe(size);
+
+    // Total byte coverage must equal file size
+    const totalCoverage = pages.reduce((sum, p) => sum + (p.endOffset - p.startOffset), 0);
+    expect(totalCoverage).toBe(size);
+
+    // Concatenated content must match the original file content exactly
+    const concatenated = pages.map(p => p.content).reverse().join("");
+    expect(concatenated).toBe(chars);
+  });
+
+  it("returns continuous byte ranges with 4-byte emoji characters", () => {
+    const emoji = "🚀";
+    const buf = Buffer.from(emoji.repeat(15)); // 60 bytes
+    const filePath = path.join(tmpDir, "emoji.log");
+    fs.writeFileSync(filePath, buf);
+    const size = buf.length;
+
+    let before = size;
+    const pages: Array<{ content: string; startOffset: number; endOffset: number }> = [];
+    for (let i = 0; i < 10; i++) {
+      const r = readLogSlice(filePath, { before, limit: 12 });
+      if (r.content.length === 0) break;
+      pages.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) break;
+    }
+
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    expect(pages[pages.length - 1].startOffset).toBe(0);
+    expect(pages[0].endOffset).toBe(size);
+
+    const totalCoverage = pages.reduce((sum, p) => sum + (p.endOffset - p.startOffset), 0);
+    expect(totalCoverage).toBe(size);
+
+    const concatenated = pages.map(p => p.content).reverse().join("");
+    expect(concatenated).toBe(buf.toString("utf8"));
+  });
+});
+
+describe("readLogSlice coverage correctness for tail+before", () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-coverage-"));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("tail then before pagination produces full file coverage", () => {
+    const lines: string[] = [];
+    for (let i = 0; i < 100; i++) {
+      lines.push(`line-${i.toString().padStart(3, "0")}\n`);
+    }
+    const content = lines.join("");
+    const filePath = path.join(tmpDir, "coverage.log");
+    fs.writeFileSync(filePath, content, "utf8");
+    const size = Buffer.byteLength(content, "utf8");
+
+    const tail = readLogSlice(filePath, { tail: true, limit: 200 });
+    expect(tail.endOffset).toBe(size);
+    expect(tail.startOffset).toBeGreaterThan(0);
+    expect(tail.hasMoreBefore).toBe(true);
+
+    let before = tail.startOffset;
+    const segments = [tail];
+    while (before > 0) {
+      const r = readLogSlice(filePath, { before, limit: 200 });
+      if (r.content.length === 0) break;
+      segments.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) break;
+    }
+
+    const first = segments[segments.length - 1];
+    expect(first.startOffset).toBe(0);
+    expect(first.hasMoreBefore).toBe(false);
+
+    for (let i = segments.length - 1; i > 0; i--) {
+      expect(segments[i].endOffset).toBe(segments[i - 1].startOffset);
+    }
+  });
+
+  it("before pagination with boundary-straddling content produces no coverage gaps", () => {
+    const emoji = "🌍";
+    const content = "A" + emoji.repeat(10) + "B" + emoji.repeat(10) + "C";
+    const filePath = path.join(tmpDir, "straddle.log");
+    fs.writeFileSync(filePath, content, "utf8");
+    const size = Buffer.byteLength(content, "utf8");
+
+    const limit = 20;
+    let before = size;
+    const pages: Array<{ startOffset: number; endOffset: number; content: string }> = [];
+    while (before > 0) {
+      const r = readLogSlice(filePath, { before, limit });
+      if (r.content.length === 0) break;
+      pages.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) break;
+    }
+
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    const oldest = pages[pages.length - 1];
+    expect(oldest.startOffset).toBe(0);
+    expect(oldest.hasMoreBefore).toBe(false);
+
+    const newest = pages[0];
+    expect(newest.endOffset).toBe(size);
+
+    const fullRangeCovered = pages.reduce((sum, p) => sum + (p.endOffset - p.startOffset), 0);
+    expect(fullRangeCovered).toBe(size);
+  });
+});
+
+describe("client-side JS contract: progress merge and cycle follow", () => {
+  it("generates JavaScript with progressMerged logic in renderTimeline", async () => {
+    const { getAssetsHtml } = await import("./workflow-web-assets.js");
+    const html = getAssetsHtml();
+    const scriptMatch = html.match(/<script>([\s\S]*?)<\/script>/);
+    expect(scriptMatch).not.toBeNull();
+    const scriptContent = scriptMatch![1];
+
+    expect(scriptContent).toContain("progressMerged");
+    expect(scriptContent).toContain("function renderTimeline");
+    expect(scriptContent).toContain("function appendTimelineEntries");
+    expect(scriptContent).toContain("function setupSSE");
+    expect(scriptContent).toContain("function returnToLive");
+  });
+});
+
+describe("readLogSlice edge cases", () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-edge-"));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("handles empty file", () => {
+    const filePath = path.join(tmpDir, "empty.log");
+    fs.writeFileSync(filePath, "", "utf8");
+
+    const r = readLogSlice(filePath, { offset: 0, limit: 100 });
+    expect(r.content).toBe("");
+    expect(r.startOffset).toBe(0);
+    expect(r.endOffset).toBe(0);
+    expect(r.size).toBe(0);
+    expect(r.hasMore).toBe(false);
+    expect(r.hasMoreBefore).toBe(false);
+
+    const rTail = readLogSlice(filePath, { tail: true, limit: 100 });
+    expect(rTail.content).toBe("");
+    expect(rTail.endOffset).toBe(0);
+
+    const rBefore = readLogSlice(filePath, { before: 0, limit: 100 });
+    expect(rBefore.content).toBe("");
+    expect(rBefore.endOffset).toBe(0);
+  });
+
+  it("handles before=0 edge case", () => {
+    const filePath = path.join(tmpDir, "small.log");
+    fs.writeFileSync(filePath, "hello", "utf8");
+
+    const r = readLogSlice(filePath, { before: 0, limit: 100 });
+    expect(r.content).toBe("");
+    expect(r.startOffset).toBe(0);
+    expect(r.endOffset).toBe(0);
+    expect(r.hasMore).toBe(true);
+  });
+
+  it("handles before less than limit", () => {
+    const filePath = path.join(tmpDir, "small2.log");
+    fs.writeFileSync(filePath, "Hello World!", "utf8");
+
+    const r = readLogSlice(filePath, { before: 5, limit: 100 });
+    expect(r.startOffset).toBe(0);
+    expect(r.endOffset).toBe(5);
+    expect(r.content).toBe("Hello");
+    expect(r.hasMoreBefore).toBe(false);
+  });
+
+  it("tail returns last N bytes correctly", () => {
+    const filePath = path.join(tmpDir, "tail-test.log");
+    fs.writeFileSync(filePath, "abcdefghijklmnopqrstuvwxyz", "utf8");
+
+    const r = readLogSlice(filePath, { tail: true, limit: 5 });
+    expect(r.content).toBe("vwxyz");
+    expect(r.endOffset).toBe(26);
+    expect(r.startOffset).toBe(21);
+    expect(r.hasMoreBefore).toBe(true);
+    expect(r.hasMore).toBe(false);
+  });
+
+  it("before pagination single-byte ASCII produces exact coverage", () => {
+    const filePath = path.join(tmpDir, "ascii.log");
+    // "line 1\n" = 7 bytes, 5 lines = 35 bytes
+    fs.writeFileSync(filePath, "line 1\nline 2\nline 3\nline 4\nline 5\n", "utf8");
+
+    const size = fs.statSync(filePath).size;
+
+    const p1 = readLogSlice(filePath, { before: size, limit: 15 });   // [20, 35)
+    const p2 = readLogSlice(filePath, { before: p1.startOffset, limit: 15 }); // [5, 20)
+    const p3 = readLogSlice(filePath, { before: p2.startOffset, limit: 15 }); // [0, 5)
+
+    expect(p3.endOffset).toBe(p2.startOffset);
+    expect(p2.endOffset).toBe(p1.startOffset);
+    expect(p3.startOffset).toBe(0);
+
+    const combined = p3.content + p2.content + p1.content;
+    expect(combined).toContain("line 1");
+    expect(combined).toContain("line 5");
+  });
+});
+
+describe("API response consistency for before pagination", () => {
+  let tmpDir: string;
+  let server: http.Server;
+  let port = 14321;
+  let baseUrl: string;
+  let hash = "testhash";
+  let runId = "before-pagination-run";
+  let savedAgentDir: string | undefined;
+
+  beforeAll(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-api-before-"));
+    savedAgentDir = process.env.AGENT_WORKFLOW_DIR;
+    process.env.AGENT_WORKFLOW_DIR = tmpDir;
+
+    const runDir = path.join(tmpDir, hash, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+
+    const mockState: WorkflowState = {
+      version: "1", runId, repoHash: hash, repoRoot: "/tmp",
+      executor: "claude", status: "executing", maxCycles: 5, currentCycle: 1,
+      cycles: [{ cycleIndex: 1, startedAt: new Date().toISOString(), executorAttemptLogs: ["cycle-1-exec.log"] }],
+      plan: { version: "1", title: "Before Pagination Test", planMarkdown: "", scope: [], acceptanceCriteria: [], verificationCommands: [] },
+      createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+    };
+    writeState(runDir, mockState);
+
+    const logPath = attemptLogPath(runDir, 1, 0);
+    const content = "line one\nline two\nline three\nline four\nline five\n";
+    fs.writeFileSync(logPath, content, "utf8");
+
+    server = await startWorkflowWebServer(port);
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  afterAll(() => {
+    return new Promise<void>((resolve) => {
+      server.close(() => {
+        if (savedAgentDir === undefined) delete process.env.AGENT_WORKFLOW_DIR;
+        else process.env.AGENT_WORKFLOW_DIR = savedAgentDir;
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        resolve();
+      });
+    });
+  });
+
+  it("before pagination via API returns consistent offsets", async () => {
+    const tailRes = await fetch(`${baseUrl}/api/runs/${runId}/logs?cycle=1&attempt=0&tail=1&limit=20`);
+    const tail = await tailRes.json();
+    expect(tail.hasMoreBefore).toBe(true);
+    expect(tail.startOffset).toBeGreaterThan(0);
+
+    let before = tail.startOffset;
+    const pages = [tail];
+    let guard = 0;
+    while (before > 0 && guard++ < 10) {
+      const res = await fetch(`${baseUrl}/api/runs/${runId}/logs?cycle=1&attempt=0&before=${before}&limit=20`);
+      const data = await res.json();
+      pages.push(data);
+      before = data.startOffset;
+      if (!data.hasMoreBefore) break;
+    }
+
+    const oldest = pages[pages.length - 1];
+    expect(oldest.startOffset).toBe(0);
+    expect(oldest.hasMoreBefore).toBe(false);
+
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    const newest = pages[0];
+    expect(newest.endOffset).toBe(tail.size);
+  });
+
+  it("before pagination with multi-byte UTF-8 via API", async () => {
+    const runDir = path.join(tmpDir, hash, runId);
+    const logPath = attemptLogPath(runDir, 1, 0);
+    const emojiLine = "🚀🌈🦄 test log line\n";
+    const extraContent = emojiLine.repeat(10);
+    fs.appendFileSync(logPath, extraContent, "utf8");
+
+    const size = fs.statSync(logPath).size;
+
+    const limit = 30;
+    let before = size;
+    const pages: any[] = [];
+    let guard = 0;
+    while (before > 0 && guard++ < 20) {
+      const res = await fetch(`${baseUrl}/api/runs/${runId}/logs?cycle=1&attempt=0&before=${before}&limit=${limit}`);
+      const data = await res.json();
+      pages.push(data);
+      before = data.startOffset;
+      if (!data.hasMoreBefore) break;
+    }
+
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    expect(pages[pages.length - 1].startOffset).toBe(0);
+    expect(pages[0].endOffset).toBe(size);
+
+    const totalCovered = pages.reduce((sum: number, p: any) => sum + (p.endOffset - p.startOffset), 0);
+    expect(totalCovered).toBe(size);
+  });
+});
+
+describe("readLogSlice before mode with boundary-straddling multi-byte UTF-8", () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-workflow-boundary-utf8-"));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("handles 3-byte character split across before boundary with content integrity", () => {
+    const content = "ABC" + "中".repeat(10) + "XYZ";
+    const filePath = path.join(tmpDir, "boundary-3byte.log");
+    fs.writeFileSync(filePath, content, "utf8");
+    const size = Buffer.byteLength(content, "utf8");
+
+    let before = size;
+    const pages: Array<{ content: string; startOffset: number; endOffset: number }> = [];
+    for (let i = 0; i < 10; i++) {
+      const r = readLogSlice(filePath, { before, limit: 15 });
+      if (r.content.length === 0) break;
+      pages.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) break;
+    }
+
+    // Verify continuous coverage
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    expect(pages[pages.length - 1].startOffset).toBe(0);
+    expect(pages[0].endOffset).toBe(size);
+
+    const totalCovered = pages.reduce((sum, p) => sum + (p.endOffset - p.startOffset), 0);
+    expect(totalCovered).toBe(size);
+
+    // Concatenated content must match original
+    const concatenated = pages.map(p => p.content).reverse().join("");
+    expect(concatenated).toBe(content);
+  });
+
+  it("handles 4-byte character split across before boundary with content integrity", () => {
+    const content = "START:" + "🚀".repeat(8) + ":END";
+    const filePath = path.join(tmpDir, "boundary-4byte.log");
+    fs.writeFileSync(filePath, content, "utf8");
+    const size = Buffer.byteLength(content, "utf8");
+
+    let before = size;
+    const pages: Array<{ startOffset: number; endOffset: number; content: string }> = [];
+    for (let i = 0; i < 10; i++) {
+      const r = readLogSlice(filePath, { before, limit: 14 });
+      if (r.content.length === 0) break;
+      pages.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) break;
+    }
+
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    expect(pages[pages.length - 1].startOffset).toBe(0);
+    expect(pages[0].endOffset).toBe(size);
+
+    const totalCovered = pages.reduce((sum, p) => sum + (p.endOffset - p.startOffset), 0);
+    expect(totalCovered).toBe(size);
+
+    const concatenated = pages.map(p => p.content).reverse().join("");
+    expect(concatenated).toBe(content);
+  });
+
+  it("does not drop bytes across page boundaries with mixed ASCII and multi-byte", () => {
+    const content = "AAAAA" + "ë".repeat(3) + "BBBBB" + "ñ".repeat(3) + "CCCCC";
+    const filePath = path.join(tmpDir, "mixed-ascii-utf8.log");
+    fs.writeFileSync(filePath, content, "utf8");
+    const size = Buffer.byteLength(content, "utf8");
+
+    let before = size;
+    const pages: Array<{ startOffset: number; endOffset: number; content: string }> = [];
+    let iterations = 0;
+    while (before > 0 && iterations++ < 20) {
+      const r = readLogSlice(filePath, { before, limit: 13 });
+      if (r.content.length === 0) break;
+      pages.push(r);
+      before = r.startOffset;
+      if (!r.hasMoreBefore) {
+        expect(r.startOffset).toBe(0);
+        break;
+      }
+    }
+
+    for (let i = pages.length - 1; i > 0; i--) {
+      expect(pages[i].endOffset).toBe(pages[i - 1].startOffset);
+    }
+
+    const totalBytes = pages.reduce((sum, p) => sum + (p.endOffset - p.startOffset), 0);
+    expect(totalBytes).toBe(size);
+
+    const concatenated = pages.map(p => p.content).reverse().join("");
+    expect(concatenated).toBe(content);
+  });
+});
diff --git a/src/workflow-web.ts b/src/workflow-web.ts
index 6431293..4098304 100644
--- a/src/workflow-web.ts
+++ b/src/workflow-web.ts
@@ -249,33 +249,100 @@ export function readLogSlice(
   let usable = buffer;
   let startOffset = start;
 
-  // Skip leading continuation bytes when reading mid-file.
-  if (startOffset > 0) {
-    const skip = leadingIncompleteUtf8Bytes(usable);
-    if (skip > 0) {
-      usable = Buffer.from(usable.subarray(skip));
-      startOffset += skip;
+  const isBeforeMode = opts.before !== undefined;
+
+  if (!isBeforeMode) {
+    // Skip leading continuation bytes when reading mid-file (forward/tail only).
+    if (startOffset > 0) {
+      const skip = leadingIncompleteUtf8Bytes(usable);
+      if (skip > 0) {
+        usable = Buffer.from(usable.subarray(skip));
+        startOffset += skip;
+      }
     }
+
+    // Drop trailing incomplete multi-byte sequence (forward/tail only).
+    const { complete } = splitCompleteUtf8(usable);
+    let contentBuf = complete.length > 0 ? complete : usable;
+    // If complete is empty but we have bytes at EOF, still decode (replacement chars).
+    if (complete.length === 0 && end >= size && usable.length > 0) {
+      contentBuf = usable;
+    }
+    const endOffset = startOffset + contentBuf.length;
+    const content = contentBuf.toString("utf8");
+
+    return {
+      content,
+      startOffset,
+      endOffset,
+      nextOffset: endOffset,
+      size,
+      hasMore: endOffset < size,
+      hasMoreBefore: startOffset > 0,
+    };
   }
 
-  // Drop trailing incomplete multi-byte sequence.
-  const { complete } = splitCompleteUtf8(usable);
-  let contentBuf = complete.length > 0 ? complete : usable;
-  // If complete is empty but we have bytes at EOF, still decode (replacement chars).
-  if (complete.length === 0 && end >= size && usable.length > 0) {
-    contentBuf = usable;
+  // Before mode: extend the read range backward (up to 3 bytes) so the start
+  // boundary falls on a complete UTF-8 code point.  The end boundary (`end =
+  // before`) is inherently at a non-continuation byte because it was set from
+  // an adjacent page's startOffset (either a tail page that already skipped
+  // leading continuations, or a prior before page that was extended backward
+  // to a lead byte).  This eliminates replacement characters at boundaries
+  // while keeping startOffset/endOffset continuous with adjacent pages.
+  let adjustedStart = start;
+
+  if (adjustedStart > 0) {
+    const backtrack = Math.min(adjustedStart, 3);
+    const probeBuf = Buffer.alloc(backtrack);
+    const pfd = fs.openSync(logPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    try {
+      fs.readSync(pfd, probeBuf, 0, backtrack, adjustedStart - backtrack);
+    } finally {
+      fs.closeSync(pfd);
+    }
+    // Scan backward from the byte just before `start` looking for a lead byte.
+    for (let i = probeBuf.length - 1; i >= 0; i--) {
+      if ((probeBuf[i] & 0xC0) === 0xC0) {
+        // Lead byte found – extend start to include the full multi-byte character.
+        adjustedStart = adjustedStart - backtrack + i;
+        break;
+      }
+      if ((probeBuf[i] & 0x80) === 0x00) {
+        // ASCII byte – the character at `start` starts fresh, no adjustment.
+        break;
+      }
+      // Continuation byte – the lead is further back.
+    }
+    // If the probe only found continuation bytes (invalid >3B chain),
+    // leave adjustedStart unchanged; splitCompleteUtf8 will handle it.
   }
-  const endOffset = startOffset + contentBuf.length;
+
+  // Read the adjusted range
+  const readLen = end - adjustedStart;
+  const readBuf = Buffer.alloc(readLen);
+  const rfd = fs.openSync(logPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    fs.readSync(rfd, readBuf, 0, readLen, adjustedStart);
+  } finally {
+    fs.closeSync(rfd);
+  }
+
+  // Drop trailing incomplete sequence (e.g. lead byte at EOF whose
+  // continuation bytes haven't been written yet).
+  const { complete } = splitCompleteUtf8(readBuf);
+  let contentBuf = complete.length > 0 ? complete : readBuf;
+  const contentEnd = adjustedStart + contentBuf.length;
+
   const content = contentBuf.toString("utf8");
 
   return {
     content,
-    startOffset,
-    endOffset,
-    nextOffset: endOffset,
+    startOffset: adjustedStart,
+    endOffset: contentEnd,
+    nextOffset: contentEnd,
     size,
-    hasMore: endOffset < size,
-    hasMoreBefore: startOffset > 0,
+    hasMore: contentEnd < size,
+    hasMoreBefore: adjustedStart > 0,
   };
 }