@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/src/backend/lib/native-task-history-reader.js

@@ -1,526 +1,526 @@
-'use strict';
-
-// Native task history reader - serves native background-task facts for one
-// session out of that session's durable history file. The { file, scope }
-// pair is server-trusted input: the file path never comes from a cursor or
-// a client. The reader opens the file read-only, streams it in bounded
-// chunks (the full log text never resides in memory), measures real byte
-// offsets - multi-byte UTF-8 and CRLF included - and feeds every accepted
-// row to the reviewed NativeTaskHistoryIndex, which owns all identity and
-// attribution decisions. Public cursor tokens are opaque base64url values
-// binding version, file era (fileId), full scope, full native task ref,
-// the exclusive before-offset and an anchor row hash; they never carry a
-// path. Era/truncation/anchor divergence is always an explicit 409 resync
-// signal, never a silent empty page. Legacy files without a fileId stay
-// untouched: task history is explicitly unavailable for them.
-
-const crypto = require('node:crypto');
-const fsp = require('node:fs/promises');
-const path = require('node:path');
-const { NativeTaskHistoryIndex } = require('./native-task-history-index');
-const { createTaskScope, createNativeTaskRef, nativeTaskKey, sameTaskScope } = require('./task-identity');
-
-const HISTORY_SCHEMA = 'workbench-history/v1';
-const CURSOR_VERSION = 1;
-const CURSOR_TOKEN_RE = /^[A-Za-z0-9_-]+$/;
-const CURSOR_HASH_RE = /^[0-9a-f]{64}$/;
-const CURSOR_KEYS = ['a', 'b', 'f', 's', 't', 'v'];
-const SCOPE_KEYS = ['contextId', 'parentSessionId', 'storeScope'];
-const REF_KEYS = ['contextId', 'kind', 'ownerRunId', 'parentSessionId', 'storeScope', 'taskId'];
-const MAX_CURSOR_CHARS = 4096;
-const MAX_PATH_CHARS = 4096;
-const MAX_ID_CHARS = 512;
-const DEFAULT_LIMIT = 100;
-const MAX_LIMIT = 1000;
-const SCAN_CHUNK_BYTES = 1024 * 1024;
-const MAX_ROW_BYTES = 16 * 1024 * 1024;
-const MAX_PAGE_BYTES = 4 * 1024 * 1024;
-const CACHE_MAX_READERS = 8;
-const HEADER_PROBE_BYTES = 64 * 1024;
-const READER_DIAGNOSTIC_CAP = 100;
-const RESPONSE_DIAGNOSTIC_CAP = 20;
-
-const readerCache = new Map();
-let cacheClock = 0;
-
-function fail(code, status, message) { throw Object.assign(new Error(message), { code, status }); }
-
-function isId(value, max = MAX_ID_CHARS) { return typeof value === 'string' && value !== '' && value.length <= max; }
-
-function rowContentHash(event) { return crypto.createHash('sha256').update(JSON.stringify(event)).digest('hex'); }
-
-function encodeCursor(payload) { return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url'); }
-
-function decodeCursor(token) {
-  if (typeof token !== 'string' || token === '' || token.length > MAX_CURSOR_CHARS || !CURSOR_TOKEN_RE.test(token)) {
-    fail('INVALID_CURSOR', 400, 'cursor must be an opaque base64url token');
-  }
-  let parsed = null;
-  try { parsed = JSON.parse(Buffer.from(token, 'base64url').toString('utf8')); } catch (error) { parsed = null; }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) fail('INVALID_CURSOR', 400, 'cursor payload must be a JSON object');
-  if (JSON.stringify(Object.keys(parsed).sort()) !== JSON.stringify(CURSOR_KEYS)) fail('INVALID_CURSOR', 400, 'cursor payload fields are invalid');
-  if (parsed.v !== CURSOR_VERSION) fail('INVALID_CURSOR', 400, 'cursor version is not supported');
-  if (!isId(parsed.f)) fail('INVALID_CURSOR', 400, 'cursor file era is invalid');
-  if (!parsed.s || typeof parsed.s !== 'object' || Array.isArray(parsed.s)
-    || JSON.stringify(Object.keys(parsed.s).sort()) !== JSON.stringify(SCOPE_KEYS)) fail('INVALID_CURSOR', 400, 'cursor scope is invalid');
-  for (const key of SCOPE_KEYS) if (!isId(parsed.s[key])) fail('INVALID_CURSOR', 400, 'cursor scope is invalid');
-  if (!parsed.t || typeof parsed.t !== 'object' || Array.isArray(parsed.t) || parsed.t.kind !== 'native-task'
-    || JSON.stringify(Object.keys(parsed.t).sort()) !== JSON.stringify(REF_KEYS)) fail('INVALID_CURSOR', 400, 'cursor task reference is invalid');
-  for (const key of REF_KEYS) if (!isId(parsed.t[key])) fail('INVALID_CURSOR', 400, 'cursor task reference is invalid');
-  if (createNativeTaskRef(parsed.t) === null) fail('INVALID_CURSOR', 400, 'cursor task reference is invalid');
-  if (!Number.isSafeInteger(parsed.b) || parsed.b <= 0) fail('INVALID_CURSOR', 400, 'cursor offset is invalid');
-  if (!parsed.a || typeof parsed.a !== 'object' || Array.isArray(parsed.a) || Object.keys(parsed.a).length !== 2) fail('INVALID_CURSOR', 400, 'cursor anchor is invalid');
-  if (!Number.isSafeInteger(parsed.a.o) || parsed.a.o <= 0 || parsed.a.o !== parsed.b
-    || typeof parsed.a.h !== 'string' || !CURSOR_HASH_RE.test(parsed.a.h)) fail('INVALID_CURSOR', 400, 'cursor anchor is invalid');
-  return parsed;
-}
-
-class NativeTaskHistoryReader {
-  constructor({ file, scope } = {}) {
-    if (!isId(file, MAX_PATH_CHARS) || !path.isAbsolute(file)) fail('INVALID_READER_ARGS', 400, 'reader requires an absolute history file path');
-    let resolved = null;
-    try { resolved = path.resolve(file); } catch (error) { resolved = null; }
-    if (!resolved || !path.isAbsolute(resolved)) fail('INVALID_READER_ARGS', 400, 'history file path must be absolute');
-    const taskScope = createTaskScope(scope);
-    if (!taskScope) fail('INVALID_READER_ARGS', 400, 'reader requires a valid fixed TaskScope');
-    this._file = resolved;
-    this._scope = Object.freeze({ storeScope: taskScope.storeScope, contextId: taskScope.contextId, parentSessionId: taskScope.parentSessionId });
-  }
-
-  get file() { return this._file; }
-  get scope() { return { ...this._scope }; }
-
-  async listTasks() {
-    const state = await this._refresh();
-    this._requireEra(state);
-    return {
-      fileId: state.fileId,
-      tasks: state.index.listTasks(),
-      incomplete: [...state.incomplete],
-      diagnostics: this._diagnosticView(state),
-    };
-  }
-
-  async readTaskEvents(taskRef, options = {}) {
-    if (!taskRef || typeof taskRef !== 'object' || Array.isArray(taskRef)) fail('INVALID_TASK_REF', 400, 'taskRef must be a native-task reference object');
-    if (!options || typeof options !== 'object' || Array.isArray(options)) fail('INVALID_CURSOR', 400, 'options must be an object');
-    const limit = options.limit === undefined ? DEFAULT_LIMIT : options.limit;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT) fail('INVALID_LIMIT', 400, 'limit must be an integer between 1 and ' + MAX_LIMIT);
-    const ref = createNativeTaskRef(taskRef);
-    if (!ref) fail('INVALID_TASK_REF', 400, 'taskRef is not a valid native-task reference');
-    if (!sameTaskScope(ref, this._scope)) fail('SCOPE_MISMATCH', 409, 'taskRef scope does not match this reader');
-    const cursor = options.cursor === undefined || options.cursor === null ? null : decodeCursor(options.cursor);
-    const state = await this._refresh();
-    this._requireEra(state);
-    if (cursor) {
-      if (cursor.f !== state.fileId) fail('FILE_ERA_CHANGED', 409, 'history file era changed; resync from a fresh page');
-      if (cursor.s.storeScope !== this._scope.storeScope || cursor.s.contextId !== this._scope.contextId
-        || cursor.s.parentSessionId !== this._scope.parentSessionId) fail('SCOPE_MISMATCH', 409, 'cursor scope does not match this reader');
-      if (nativeTaskKey(createNativeTaskRef(cursor.t)) !== nativeTaskKey(ref)) fail('SCOPE_MISMATCH', 409, 'cursor belongs to a different task');
-    }
-    const refKey = nativeTaskKey(ref);
-    const bound = state.index.listTasks().some(task => task.taskRef && nativeTaskKey(task.taskRef) === refKey);
-    if (!bound) fail('TASK_NOT_INDEXED', 404, 'task is not present in this history');
-    let handle = null;
-    try {
-      handle = await fsp.open(this._file, 'r');
-      await this._verifyReadHandle(handle, state);
-      if (cursor) await this._verifyAnchor(handle, state, ref, cursor);
-      const page = state.index.listOffsets(ref, { before: cursor ? cursor.b : undefined, limit });
-      // Byte-cap selection keeps the NEWEST complete suffix of the window.
-      // Rows dropped by the cap are older than every returned row, stay
-      // below the next cursor bound, and are served by the following page -
-      // across all pages every servable row appears exactly once. A row
-      // that alone exceeds the cap surfaces as an explicit 413 the moment
-      // it becomes the newest candidate of a window, wherever it sits.
-      const selected = [];
-      let pageBytes = 0;
-      let capped = false;
-      for (let i = page.entries.length - 1; i >= 0; i--) {
-        const entry = page.entries[i];
-        const rowBytes = entry.endOffset - entry.offset;
-        if (selected.length === 0 && rowBytes > MAX_PAGE_BYTES) fail('ROW_TOO_LARGE', 413, 'a single history row exceeds the page byte cap');
-        if (pageBytes + rowBytes > MAX_PAGE_BYTES) { capped = true; break; }
-        selected.unshift(entry);
-        pageBytes += rowBytes;
-      }
-      const events = selected.length > 0 ? await this._readRows(handle, selected) : [];
-      const hasMore = capped || page.nextBefore !== null;
-      const nextCursor = hasMore && selected.length > 0
-        ? encodeCursor({ v: CURSOR_VERSION, f: state.fileId, s: { ...this._scope }, t: { ...ref }, b: selected[0].offset, a: { o: selected[0].offset, h: selected[0].hash } })
-        : null;
-      return {
-        events,
-        nextCursor,
-        hasMore,
-        fileId: state.fileId,
-        incomplete: [...state.incomplete],
-        diagnostics: this._diagnosticView(state),
-      };
-    } catch (error) {
-      if (error && typeof error.status === 'number') throw error;
-      fail('HISTORY_SCAN_FAULT', 500, 'history page read failed');
-    } finally {
-      if (handle) await handle.close().catch(() => {});
-    }
-  }
-
-  _requireEra(state) {
-    if (state.fileId === null) fail('TASK_HISTORY_LEGACY', 409, 'task history is unavailable for this legacy-era history file; no rewrite or migration is performed');
-  }
-
-  async _verifyAnchor(handle, state, ref, cursor) {
-    const probeBound = cursor.a.o < Number.MAX_SAFE_INTEGER ? cursor.a.o + 1 : cursor.a.o;
-    const probe = state.index.listOffsets(ref, { before: probeBound, limit: 1 });
-    const hit = probe.entries.length > 0 ? probe.entries[0] : null;
-    if (!hit || hit.offset !== cursor.a.o) {
-      if (cursor.a.o >= state.fileSize) fail('HISTORY_TRUNCATED', 409, 'history file was truncated; resync from a fresh page');
-      fail('ANCHOR_MISMATCH', 409, 'cursor anchor row is gone; resync from a fresh page');
-    }
-    if (hit.hash !== cursor.a.h) fail('ANCHOR_MISMATCH', 409, 'cursor anchor row changed; resync from a fresh page');
-    // The index hash can be stale after a same-size in-place edit (old rows
-    // are never rescanned by incremental scans), so the anchor row is
-    // re-read from disk and re-hashed before any page is served on top of
-    // it - the rows about to be returned are not enough to prove the
-    // anchor still exists as the cursor saw it.
-    const bytes = await this._readExact(handle, hit.offset, hit.endOffset);
-    if (bytes === null) fail('HISTORY_TRUNCATED', 409, 'history row is no longer fully present; resync from a fresh page');
-    let parsed = null;
-    try { parsed = JSON.parse(bytes.toString('utf8')); } catch (error) { parsed = null; }
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || rowContentHash(parsed) !== cursor.a.h) {
-      fail('ANCHOR_MISMATCH', 409, 'cursor anchor row changed on disk; resync from a fresh page');
-    }
-  }
-
-  // The page-read handle must be the same file the index was built from:
-  // a replacement between the scan and this open would otherwise serve a
-  // new file's rows under the old era. Any divergence drops the cached
-  // state so the next call rebuilds.
-  async _verifyReadHandle(handle, state) {
-    const stats = await handle.stat();
-    if (stats.dev !== state.dev || stats.ino !== state.ino) {
-      this._invalidateState(state);
-      fail('FILE_ERA_CHANGED', 409, 'history file identity changed under the reader; resync from a fresh page');
-    }
-    const line = await this._readHeaderLine(handle);
-    let header = null;
-    if (line !== null) {
-      let end = line.length;
-      if (end > 0 && line[end - 1] === 0x0A) end--;
-      if (end > 0 && line[end - 1] === 0x0D) end--;
-      try { header = JSON.parse(line.toString('utf8', 0, end)); } catch (error) { header = null; }
-    }
-    if (!header || typeof header !== 'object' || header.schema !== HISTORY_SCHEMA
-      || header.sessionId !== this._scope.parentSessionId || header.contextId !== this._scope.contextId
-      || !isId(header.fileId) || header.fileId !== state.fileId) {
-      this._invalidateState(state);
-      fail('FILE_ERA_CHANGED', 409, 'history file era diverged under the reader; resync from a fresh page');
-    }
-  }
-
-  _invalidateState(state) {
-    for (const entry of readerCache.values()) {
-      if (entry.state === state) entry.state = null;
-    }
-  }
-
-  async _readExact(handle, offset, endOffset) {
-    const length = endOffset - offset;
-    const buffer = Buffer.alloc(length);
-    let done = 0;
-    while (done < length) {
-      const { bytesRead } = await handle.read(buffer, done, length - done, offset + done);
-      if (bytesRead <= 0) return null;
-      done += bytesRead;
-    }
-    return buffer;
-  }
-
-  async _readRows(handle, entries) {
-    const events = new Array(entries.length);
-    for (let i = 0; i < entries.length; i++) {
-      const entry = entries[i];
-      const bytes = await this._readExact(handle, entry.offset, entry.endOffset);
-      if (bytes === null) fail('HISTORY_TRUNCATED', 409, 'history row is no longer fully present; resync from a fresh page');
-      let event = null;
-      try { event = JSON.parse(bytes.toString('utf8')); } catch (error) { event = null; }
-      if (!event || typeof event !== 'object' || Array.isArray(event)) fail('HISTORY_MUTATED', 409, 'history row no longer parses; resync from a fresh page');
-      if (rowContentHash(event) !== entry.hash) fail('HISTORY_MUTATED', 409, 'history row content diverged from the index; resync from a fresh page');
-      events[i] = event;
-    }
-    return events;
-  }
-
-  async _refresh() {
-    const cacheKey = JSON.stringify([this._file, this._scope.storeScope, this._scope.contextId, this._scope.parentSessionId]);
-    let entry = readerCache.get(cacheKey);
-    if (!entry) {
-      entry = { lastUsed: 0, state: null, chain: null };
-      readerCache.set(cacheKey, entry);
-    }
-    entry.lastUsed = ++cacheClock;
-    while (readerCache.size > CACHE_MAX_READERS) {
-      let oldestKey = null;
-      let oldest = Infinity;
-      for (const [key, value] of readerCache) if (value !== entry && value.lastUsed < oldest) { oldest = value.lastUsed; oldestKey = key; }
-      if (oldestKey === null) break;
-      readerCache.delete(oldestKey);
-    }
-    // One scan at a time per (file, scope): concurrent callers queue behind
-    // the in-flight refresh instead of racing incremental scans over the
-    // shared mutable index state.
-    const run = async () => {
-      let stats = null;
-      try { stats = await fsp.lstat(this._file); }
-      catch (error) {
-        if (error && error.code === 'ENOENT') fail('HISTORY_NOT_FOUND', 404, 'history file does not exist');
-        fail('HISTORY_OPEN_FAILED', 500, 'history file cannot be examined');
-      }
-      if (stats.isSymbolicLink() || !stats.isFile()) fail('HISTORY_NOT_REGULAR', 400, 'history file must be a regular file, not a symlink or device');
-      let state = entry.state;
-      const replaced = state !== null && (state.dev !== stats.dev || state.ino !== stats.ino);
-      const truncated = state !== null && !replaced && stats.size < state.indexedBytes;
-      if (state === null || replaced || truncated) {
-        const priorBytes = state === null ? 0 : state.indexedBytes;
-        state = {
-          file: this._file,
-          scope: { ...this._scope },
-          index: new NativeTaskHistoryIndex({ ...this._scope }),
-          fileId: null,
-          fileSize: stats.size,
-          mtimeMs: stats.mtimeMs,
-          dev: stats.dev,
-          ino: stats.ino,
-          indexedBytes: 0,
-          incomplete: new Set(),
-          diagnostics: [],
-          scanned: false,
-        };
-        entry.state = state;
-        if (truncated) this._diag(state, 'history-truncated-rebuilt', { previousIndexedBytes: priorBytes });
-      }
-      const unchanged = state.scanned && stats.size === state.indexedBytes && stats.mtimeMs === state.mtimeMs;
-      if (!unchanged) await this._scan(state);
-      return state;
-    };
-    const prior = entry.chain || Promise.resolve();
-    const next = prior.then(run, run);
-    entry.chain = next.then(() => {}, () => {});
-    return await next;
-  }
-
-  async _scan(state) {
-    let handle = null;
-    try {
-      handle = await fsp.open(this._file, 'r');
-      const opened = await handle.stat();
-      if (state.indexedBytes > 0) {
-        const priorBytes = state.indexedBytes;
-        let rebuild = opened.size < priorBytes;
-        let reason = 'history-truncated-rebuilt';
-        if (!rebuild) {
-          const header = await this._readHeaderLine(handle);
-          if (header === null) {
-            rebuild = true;
-            reason = 'history-replaced-rebuilt';
-          } else {
-            const priorFileId = state.fileId;
-            this._consumeHeader(state, header);
-            if (state.fileId !== priorFileId) {
-              rebuild = true;
-              reason = 'history-replaced-rebuilt';
-            }
-          }
-        }
-        if (rebuild) {
-          state.index = new NativeTaskHistoryIndex({ ...this._scope });
-          state.fileId = null;
-          state.indexedBytes = 0;
-          state.incomplete = new Set();
-          state.diagnostics = [];
-          this._diag(state, reason, { previousIndexedBytes: priorBytes });
-        }
-      }
-      state.dev = opened.dev;
-      state.ino = opened.ino;
-      await this._scanFrom(state, handle);
-      const done = await handle.stat();
-      state.fileSize = done.size;
-      state.mtimeMs = done.mtimeMs;
-      state.dev = done.dev;
-      state.ino = done.ino;
-      state.scanned = true;
-    } catch (error) {
-      state.scanned = false;
-      if (error && typeof error.status === 'number') throw error;
-      fail('HISTORY_SCAN_FAULT', 500, 'history file scan failed');
-    } finally {
-      if (handle) await handle.close().catch(() => {});
-    }
-  }
-
-  async _readHeaderLine(handle) {
-    const probe = Buffer.alloc(HEADER_PROBE_BYTES);
-    const { bytesRead } = await handle.read(probe, 0, probe.length, 0);
-    const nl = probe.subarray(0, bytesRead).indexOf(0x0A);
-    if (nl === -1) return null;
-    return probe.subarray(0, nl + 1);
-  }
-
-  async _scanFrom(state, handle) {
-    const chunk = Buffer.alloc(SCAN_CHUNK_BYTES);
-    let position = state.indexedBytes;
-    let carry = null;
-    let carryStart = position;
-    let carryDropped = false;
-    for (;;) {
-      const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
-      if (bytesRead <= 0) break;
-      let cursor = 0;
-      for (;;) {
-        const nl = chunk.indexOf(0x0A, cursor);
-        if (nl === -1 || nl >= bytesRead) break;
-        const endOffset = position + nl + 1;
-        const offset = carry !== null ? carryStart : position + cursor;
-        let lineBuffer = null;
-        if (carry !== null && !carryDropped) {
-          const tail = chunk.subarray(cursor, nl + 1);
-          lineBuffer = Buffer.concat([carry, tail], carry.length + tail.length);
-        } else if (carry === null) {
-          lineBuffer = chunk.subarray(cursor, nl + 1);
-        }
-        if (lineBuffer !== null && lineBuffer.length <= MAX_ROW_BYTES) {
-          this._consumeLine(state, offset, endOffset, lineBuffer);
-        } else {
-          if (offset === 0) fail('HISTORY_HEADER_INVALID', 400, 'history file does not begin with a valid workbench-history/v1 header');
-          this._diag(state, 'scan-oversized-row', { offset, bytes: lineBuffer === null ? null : lineBuffer.length });
-          state.incomplete.add('oversized-row');
-        }
-        carry = null;
-        carryDropped = false;
-        cursor = nl + 1;
-      }
-      if (cursor < bytesRead) {
-        const rest = Buffer.from(chunk.subarray(cursor, bytesRead));
-        if (carry !== null) {
-          if (carryDropped || carry.length + rest.length > MAX_ROW_BYTES) {
-            if (!carryDropped) {
-              this._diag(state, 'scan-oversized-row', { offset: carryStart, bytes: carry.length + rest.length });
-              state.incomplete.add('oversized-row');
-            }
-            carryDropped = true;
-            carry = null;
-          } else {
-            carry = Buffer.concat([carry, rest], carry.length + rest.length);
-          }
-        } else if (rest.length > MAX_ROW_BYTES) {
-          this._diag(state, 'scan-oversized-row', { offset: carryStart, bytes: rest.length });
-          state.incomplete.add('oversized-row');
-          carryDropped = true;
-          carry = null;
-        } else {
-          carry = rest;
-          carryStart = position + cursor;
-        }
-      }
-      position += bytesRead;
-    }
-    if (carry !== null || carryDropped) {
-      if (carry !== null) state.incomplete.add('unfinished-tail');
-      state.indexedBytes = carryStart;
-    } else {
-      state.indexedBytes = position;
-    }
-  }
-
-  _consumeLine(state, offset, endOffset, lineBuffer) {
-    if (offset === 0) {
-      this._consumeHeader(state, lineBuffer);
-      return;
-    }
-    const event = this._parseLine(state, offset, lineBuffer);
-    if (event === null) return;
-    if (event.type === 'workbench/history-checkpoint') return;
-    if (event.type === 'workbench/history-gap') {
-      state.incomplete.add('history-gap');
-      return;
-    }
-    state.index.observe({ offset, endOffset, event });
-  }
-
-  _consumeHeader(state, lineBuffer) {
-    const header = this._parseLine(state, 0, lineBuffer);
-    if (header === null || header.schema !== HISTORY_SCHEMA || !isId(header.sessionId) || !isId(header.contextId)) {
-      fail('HISTORY_HEADER_INVALID', 400, 'history file does not begin with a valid workbench-history/v1 header');
-    }
-    if (header.sessionId !== this._scope.parentSessionId || header.contextId !== this._scope.contextId) {
-      fail('HISTORY_OWNERSHIP_MISMATCH', 409, 'history file belongs to a different session scope');
-    }
-    state.fileId = isId(header.fileId) ? header.fileId : null;
-    if (header.incomplete === true) state.incomplete.add('header-incomplete');
-  }
-
-  _parseLine(state, offset, lineBuffer) {
-    let end = lineBuffer.length;
-    if (end > 0 && lineBuffer[end - 1] === 0x0A) end--;
-    if (end > 0 && lineBuffer[end - 1] === 0x0D) end--;
-    let parsed = null;
-    try { parsed = JSON.parse(lineBuffer.toString('utf8', 0, end)); } catch (error) { parsed = null; }
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      this._diag(state, 'scan-corrupt-row', { offset });
-      state.incomplete.add('corrupt-row');
-      return null;
-    }
-    return parsed;
-  }
-
-  _diag(state, code, ids) {
-    if (state.diagnostics.length >= READER_DIAGNOSTIC_CAP) return;
-    state.diagnostics.push(Object.assign({ code }, ids || {}));
-  }
-
-  _diagnosticView(state) {
-    const own = state.diagnostics.map(item => Object.assign({}, item, { source: 'reader' }));
-    const indexed = state.index.diagnostics().map(item => Object.assign({}, item, { source: 'index' }));
-    const all = own.concat(indexed);
-    return {
-      items: all.slice(0, RESPONSE_DIAGNOSTIC_CAP),
-      total: all.length,
-      truncated: all.length > RESPONSE_DIAGNOSTIC_CAP,
-    };
-  }
-}
-
-function nativeTaskHistoryCacheStats() {
-  const readers = [];
-  for (const entry of readerCache.values()) {
-    const state = entry.state;
-    if (!state) continue;
-    readers.push({
-      file: state.file,
-      scope: state.scope,
-      fileId: state.fileId,
-      fileSize: state.fileSize,
-      indexedBytes: state.indexedBytes,
-      incomplete: [...state.incomplete],
-      index: state.index.stats(),
-    });
-  }
-  return { entries: readerCache.size, maxEntries: CACHE_MAX_READERS, readers };
-}
-
-function createNativeTaskHistoryReader(options) { return new NativeTaskHistoryReader(options); }
-
-module.exports = {
-  NativeTaskHistoryReader,
-  createNativeTaskHistoryReader,
-  nativeTaskHistoryCacheStats,
-  NATIVE_TASK_HISTORY_READER_LIMITS: Object.freeze({
-    defaultLimit: DEFAULT_LIMIT,
-    maxLimit: MAX_LIMIT,
-    maxPageBytes: MAX_PAGE_BYTES,
-    maxRowBytes: MAX_ROW_BYTES,
-    scanChunkBytes: SCAN_CHUNK_BYTES,
-    maxCursorChars: MAX_CURSOR_CHARS,
-  }),
-};
+'use strict';
+
+// Native task history reader - serves native background-task facts for one
+// session out of that session's durable history file. The { file, scope }
+// pair is server-trusted input: the file path never comes from a cursor or
+// a client. The reader opens the file read-only, streams it in bounded
+// chunks (the full log text never resides in memory), measures real byte
+// offsets - multi-byte UTF-8 and CRLF included - and feeds every accepted
+// row to the reviewed NativeTaskHistoryIndex, which owns all identity and
+// attribution decisions. Public cursor tokens are opaque base64url values
+// binding version, file era (fileId), full scope, full native task ref,
+// the exclusive before-offset and an anchor row hash; they never carry a
+// path. Era/truncation/anchor divergence is always an explicit 409 resync
+// signal, never a silent empty page. Legacy files without a fileId stay
+// untouched: task history is explicitly unavailable for them.
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { NativeTaskHistoryIndex } = require('./native-task-history-index');
+const { createTaskScope, createNativeTaskRef, nativeTaskKey, sameTaskScope } = require('./task-identity');
+
+const HISTORY_SCHEMA = 'workbench-history/v1';
+const CURSOR_VERSION = 1;
+const CURSOR_TOKEN_RE = /^[A-Za-z0-9_-]+$/;
+const CURSOR_HASH_RE = /^[0-9a-f]{64}$/;
+const CURSOR_KEYS = ['a', 'b', 'f', 's', 't', 'v'];
+const SCOPE_KEYS = ['contextId', 'parentSessionId', 'storeScope'];
+const REF_KEYS = ['contextId', 'kind', 'ownerRunId', 'parentSessionId', 'storeScope', 'taskId'];
+const MAX_CURSOR_CHARS = 4096;
+const MAX_PATH_CHARS = 4096;
+const MAX_ID_CHARS = 512;
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+const SCAN_CHUNK_BYTES = 1024 * 1024;
+const MAX_ROW_BYTES = 16 * 1024 * 1024;
+const MAX_PAGE_BYTES = 4 * 1024 * 1024;
+const CACHE_MAX_READERS = 8;
+const HEADER_PROBE_BYTES = 64 * 1024;
+const READER_DIAGNOSTIC_CAP = 100;
+const RESPONSE_DIAGNOSTIC_CAP = 20;
+
+const readerCache = new Map();
+let cacheClock = 0;
+
+function fail(code, status, message) { throw Object.assign(new Error(message), { code, status }); }
+
+function isId(value, max = MAX_ID_CHARS) { return typeof value === 'string' && value !== '' && value.length <= max; }
+
+function rowContentHash(event) { return crypto.createHash('sha256').update(JSON.stringify(event)).digest('hex'); }
+
+function encodeCursor(payload) { return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url'); }
+
+function decodeCursor(token) {
+  if (typeof token !== 'string' || token === '' || token.length > MAX_CURSOR_CHARS || !CURSOR_TOKEN_RE.test(token)) {
+    fail('INVALID_CURSOR', 400, 'cursor must be an opaque base64url token');
+  }
+  let parsed = null;
+  try { parsed = JSON.parse(Buffer.from(token, 'base64url').toString('utf8')); } catch (error) { parsed = null; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) fail('INVALID_CURSOR', 400, 'cursor payload must be a JSON object');
+  if (JSON.stringify(Object.keys(parsed).sort()) !== JSON.stringify(CURSOR_KEYS)) fail('INVALID_CURSOR', 400, 'cursor payload fields are invalid');
+  if (parsed.v !== CURSOR_VERSION) fail('INVALID_CURSOR', 400, 'cursor version is not supported');
+  if (!isId(parsed.f)) fail('INVALID_CURSOR', 400, 'cursor file era is invalid');
+  if (!parsed.s || typeof parsed.s !== 'object' || Array.isArray(parsed.s)
+    || JSON.stringify(Object.keys(parsed.s).sort()) !== JSON.stringify(SCOPE_KEYS)) fail('INVALID_CURSOR', 400, 'cursor scope is invalid');
+  for (const key of SCOPE_KEYS) if (!isId(parsed.s[key])) fail('INVALID_CURSOR', 400, 'cursor scope is invalid');
+  if (!parsed.t || typeof parsed.t !== 'object' || Array.isArray(parsed.t) || parsed.t.kind !== 'native-task'
+    || JSON.stringify(Object.keys(parsed.t).sort()) !== JSON.stringify(REF_KEYS)) fail('INVALID_CURSOR', 400, 'cursor task reference is invalid');
+  for (const key of REF_KEYS) if (!isId(parsed.t[key])) fail('INVALID_CURSOR', 400, 'cursor task reference is invalid');
+  if (createNativeTaskRef(parsed.t) === null) fail('INVALID_CURSOR', 400, 'cursor task reference is invalid');
+  if (!Number.isSafeInteger(parsed.b) || parsed.b <= 0) fail('INVALID_CURSOR', 400, 'cursor offset is invalid');
+  if (!parsed.a || typeof parsed.a !== 'object' || Array.isArray(parsed.a) || Object.keys(parsed.a).length !== 2) fail('INVALID_CURSOR', 400, 'cursor anchor is invalid');
+  if (!Number.isSafeInteger(parsed.a.o) || parsed.a.o <= 0 || parsed.a.o !== parsed.b
+    || typeof parsed.a.h !== 'string' || !CURSOR_HASH_RE.test(parsed.a.h)) fail('INVALID_CURSOR', 400, 'cursor anchor is invalid');
+  return parsed;
+}
+
+class NativeTaskHistoryReader {
+  constructor({ file, scope } = {}) {
+    if (!isId(file, MAX_PATH_CHARS) || !path.isAbsolute(file)) fail('INVALID_READER_ARGS', 400, 'reader requires an absolute history file path');
+    let resolved = null;
+    try { resolved = path.resolve(file); } catch (error) { resolved = null; }
+    if (!resolved || !path.isAbsolute(resolved)) fail('INVALID_READER_ARGS', 400, 'history file path must be absolute');
+    const taskScope = createTaskScope(scope);
+    if (!taskScope) fail('INVALID_READER_ARGS', 400, 'reader requires a valid fixed TaskScope');
+    this._file = resolved;
+    this._scope = Object.freeze({ storeScope: taskScope.storeScope, contextId: taskScope.contextId, parentSessionId: taskScope.parentSessionId });
+  }
+
+  get file() { return this._file; }
+  get scope() { return { ...this._scope }; }
+
+  async listTasks() {
+    const state = await this._refresh();
+    this._requireEra(state);
+    return {
+      fileId: state.fileId,
+      tasks: state.index.listTasks(),
+      incomplete: [...state.incomplete],
+      diagnostics: this._diagnosticView(state),
+    };
+  }
+
+  async readTaskEvents(taskRef, options = {}) {
+    if (!taskRef || typeof taskRef !== 'object' || Array.isArray(taskRef)) fail('INVALID_TASK_REF', 400, 'taskRef must be a native-task reference object');
+    if (!options || typeof options !== 'object' || Array.isArray(options)) fail('INVALID_CURSOR', 400, 'options must be an object');
+    const limit = options.limit === undefined ? DEFAULT_LIMIT : options.limit;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT) fail('INVALID_LIMIT', 400, 'limit must be an integer between 1 and ' + MAX_LIMIT);
+    const ref = createNativeTaskRef(taskRef);
+    if (!ref) fail('INVALID_TASK_REF', 400, 'taskRef is not a valid native-task reference');
+    if (!sameTaskScope(ref, this._scope)) fail('SCOPE_MISMATCH', 409, 'taskRef scope does not match this reader');
+    const cursor = options.cursor === undefined || options.cursor === null ? null : decodeCursor(options.cursor);
+    const state = await this._refresh();
+    this._requireEra(state);
+    if (cursor) {
+      if (cursor.f !== state.fileId) fail('FILE_ERA_CHANGED', 409, 'history file era changed; resync from a fresh page');
+      if (cursor.s.storeScope !== this._scope.storeScope || cursor.s.contextId !== this._scope.contextId
+        || cursor.s.parentSessionId !== this._scope.parentSessionId) fail('SCOPE_MISMATCH', 409, 'cursor scope does not match this reader');
+      if (nativeTaskKey(createNativeTaskRef(cursor.t)) !== nativeTaskKey(ref)) fail('SCOPE_MISMATCH', 409, 'cursor belongs to a different task');
+    }
+    const refKey = nativeTaskKey(ref);
+    const bound = state.index.listTasks().some(task => task.taskRef && nativeTaskKey(task.taskRef) === refKey);
+    if (!bound) fail('TASK_NOT_INDEXED', 404, 'task is not present in this history');
+    let handle = null;
+    try {
+      handle = await fsp.open(this._file, 'r');
+      await this._verifyReadHandle(handle, state);
+      if (cursor) await this._verifyAnchor(handle, state, ref, cursor);
+      const page = state.index.listOffsets(ref, { before: cursor ? cursor.b : undefined, limit });
+      // Byte-cap selection keeps the NEWEST complete suffix of the window.
+      // Rows dropped by the cap are older than every returned row, stay
+      // below the next cursor bound, and are served by the following page -
+      // across all pages every servable row appears exactly once. A row
+      // that alone exceeds the cap surfaces as an explicit 413 the moment
+      // it becomes the newest candidate of a window, wherever it sits.
+      const selected = [];
+      let pageBytes = 0;
+      let capped = false;
+      for (let i = page.entries.length - 1; i >= 0; i--) {
+        const entry = page.entries[i];
+        const rowBytes = entry.endOffset - entry.offset;
+        if (selected.length === 0 && rowBytes > MAX_PAGE_BYTES) fail('ROW_TOO_LARGE', 413, 'a single history row exceeds the page byte cap');
+        if (pageBytes + rowBytes > MAX_PAGE_BYTES) { capped = true; break; }
+        selected.unshift(entry);
+        pageBytes += rowBytes;
+      }
+      const events = selected.length > 0 ? await this._readRows(handle, selected) : [];
+      const hasMore = capped || page.nextBefore !== null;
+      const nextCursor = hasMore && selected.length > 0
+        ? encodeCursor({ v: CURSOR_VERSION, f: state.fileId, s: { ...this._scope }, t: { ...ref }, b: selected[0].offset, a: { o: selected[0].offset, h: selected[0].hash } })
+        : null;
+      return {
+        events,
+        nextCursor,
+        hasMore,
+        fileId: state.fileId,
+        incomplete: [...state.incomplete],
+        diagnostics: this._diagnosticView(state),
+      };
+    } catch (error) {
+      if (error && typeof error.status === 'number') throw error;
+      fail('HISTORY_SCAN_FAULT', 500, 'history page read failed');
+    } finally {
+      if (handle) await handle.close().catch(() => {});
+    }
+  }
+
+  _requireEra(state) {
+    if (state.fileId === null) fail('TASK_HISTORY_LEGACY', 409, 'task history is unavailable for this legacy-era history file; no rewrite or migration is performed');
+  }
+
+  async _verifyAnchor(handle, state, ref, cursor) {
+    const probeBound = cursor.a.o < Number.MAX_SAFE_INTEGER ? cursor.a.o + 1 : cursor.a.o;
+    const probe = state.index.listOffsets(ref, { before: probeBound, limit: 1 });
+    const hit = probe.entries.length > 0 ? probe.entries[0] : null;
+    if (!hit || hit.offset !== cursor.a.o) {
+      if (cursor.a.o >= state.fileSize) fail('HISTORY_TRUNCATED', 409, 'history file was truncated; resync from a fresh page');
+      fail('ANCHOR_MISMATCH', 409, 'cursor anchor row is gone; resync from a fresh page');
+    }
+    if (hit.hash !== cursor.a.h) fail('ANCHOR_MISMATCH', 409, 'cursor anchor row changed; resync from a fresh page');
+    // The index hash can be stale after a same-size in-place edit (old rows
+    // are never rescanned by incremental scans), so the anchor row is
+    // re-read from disk and re-hashed before any page is served on top of
+    // it - the rows about to be returned are not enough to prove the
+    // anchor still exists as the cursor saw it.
+    const bytes = await this._readExact(handle, hit.offset, hit.endOffset);
+    if (bytes === null) fail('HISTORY_TRUNCATED', 409, 'history row is no longer fully present; resync from a fresh page');
+    let parsed = null;
+    try { parsed = JSON.parse(bytes.toString('utf8')); } catch (error) { parsed = null; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || rowContentHash(parsed) !== cursor.a.h) {
+      fail('ANCHOR_MISMATCH', 409, 'cursor anchor row changed on disk; resync from a fresh page');
+    }
+  }
+
+  // The page-read handle must be the same file the index was built from:
+  // a replacement between the scan and this open would otherwise serve a
+  // new file's rows under the old era. Any divergence drops the cached
+  // state so the next call rebuilds.
+  async _verifyReadHandle(handle, state) {
+    const stats = await handle.stat();
+    if (stats.dev !== state.dev || stats.ino !== state.ino) {
+      this._invalidateState(state);
+      fail('FILE_ERA_CHANGED', 409, 'history file identity changed under the reader; resync from a fresh page');
+    }
+    const line = await this._readHeaderLine(handle);
+    let header = null;
+    if (line !== null) {
+      let end = line.length;
+      if (end > 0 && line[end - 1] === 0x0A) end--;
+      if (end > 0 && line[end - 1] === 0x0D) end--;
+      try { header = JSON.parse(line.toString('utf8', 0, end)); } catch (error) { header = null; }
+    }
+    if (!header || typeof header !== 'object' || header.schema !== HISTORY_SCHEMA
+      || header.sessionId !== this._scope.parentSessionId || header.contextId !== this._scope.contextId
+      || !isId(header.fileId) || header.fileId !== state.fileId) {
+      this._invalidateState(state);
+      fail('FILE_ERA_CHANGED', 409, 'history file era diverged under the reader; resync from a fresh page');
+    }
+  }
+
+  _invalidateState(state) {
+    for (const entry of readerCache.values()) {
+      if (entry.state === state) entry.state = null;
+    }
+  }
+
+  async _readExact(handle, offset, endOffset) {
+    const length = endOffset - offset;
+    const buffer = Buffer.alloc(length);
+    let done = 0;
+    while (done < length) {
+      const { bytesRead } = await handle.read(buffer, done, length - done, offset + done);
+      if (bytesRead <= 0) return null;
+      done += bytesRead;
+    }
+    return buffer;
+  }
+
+  async _readRows(handle, entries) {
+    const events = new Array(entries.length);
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      const bytes = await this._readExact(handle, entry.offset, entry.endOffset);
+      if (bytes === null) fail('HISTORY_TRUNCATED', 409, 'history row is no longer fully present; resync from a fresh page');
+      let event = null;
+      try { event = JSON.parse(bytes.toString('utf8')); } catch (error) { event = null; }
+      if (!event || typeof event !== 'object' || Array.isArray(event)) fail('HISTORY_MUTATED', 409, 'history row no longer parses; resync from a fresh page');
+      if (rowContentHash(event) !== entry.hash) fail('HISTORY_MUTATED', 409, 'history row content diverged from the index; resync from a fresh page');
+      events[i] = event;
+    }
+    return events;
+  }
+
+  async _refresh() {
+    const cacheKey = JSON.stringify([this._file, this._scope.storeScope, this._scope.contextId, this._scope.parentSessionId]);
+    let entry = readerCache.get(cacheKey);
+    if (!entry) {
+      entry = { lastUsed: 0, state: null, chain: null };
+      readerCache.set(cacheKey, entry);
+    }
+    entry.lastUsed = ++cacheClock;
+    while (readerCache.size > CACHE_MAX_READERS) {
+      let oldestKey = null;
+      let oldest = Infinity;
+      for (const [key, value] of readerCache) if (value !== entry && value.lastUsed < oldest) { oldest = value.lastUsed; oldestKey = key; }
+      if (oldestKey === null) break;
+      readerCache.delete(oldestKey);
+    }
+    // One scan at a time per (file, scope): concurrent callers queue behind
+    // the in-flight refresh instead of racing incremental scans over the
+    // shared mutable index state.
+    const run = async () => {
+      let stats = null;
+      try { stats = await fsp.lstat(this._file); }
+      catch (error) {
+        if (error && error.code === 'ENOENT') fail('HISTORY_NOT_FOUND', 404, 'history file does not exist');
+        fail('HISTORY_OPEN_FAILED', 500, 'history file cannot be examined');
+      }
+      if (stats.isSymbolicLink() || !stats.isFile()) fail('HISTORY_NOT_REGULAR', 400, 'history file must be a regular file, not a symlink or device');
+      let state = entry.state;
+      const replaced = state !== null && (state.dev !== stats.dev || state.ino !== stats.ino);
+      const truncated = state !== null && !replaced && stats.size < state.indexedBytes;
+      if (state === null || replaced || truncated) {
+        const priorBytes = state === null ? 0 : state.indexedBytes;
+        state = {
+          file: this._file,
+          scope: { ...this._scope },
+          index: new NativeTaskHistoryIndex({ ...this._scope }),
+          fileId: null,
+          fileSize: stats.size,
+          mtimeMs: stats.mtimeMs,
+          dev: stats.dev,
+          ino: stats.ino,
+          indexedBytes: 0,
+          incomplete: new Set(),
+          diagnostics: [],
+          scanned: false,
+        };
+        entry.state = state;
+        if (truncated) this._diag(state, 'history-truncated-rebuilt', { previousIndexedBytes: priorBytes });
+      }
+      const unchanged = state.scanned && stats.size === state.indexedBytes && stats.mtimeMs === state.mtimeMs;
+      if (!unchanged) await this._scan(state);
+      return state;
+    };
+    const prior = entry.chain || Promise.resolve();
+    const next = prior.then(run, run);
+    entry.chain = next.then(() => {}, () => {});
+    return await next;
+  }
+
+  async _scan(state) {
+    let handle = null;
+    try {
+      handle = await fsp.open(this._file, 'r');
+      const opened = await handle.stat();
+      if (state.indexedBytes > 0) {
+        const priorBytes = state.indexedBytes;
+        let rebuild = opened.size < priorBytes;
+        let reason = 'history-truncated-rebuilt';
+        if (!rebuild) {
+          const header = await this._readHeaderLine(handle);
+          if (header === null) {
+            rebuild = true;
+            reason = 'history-replaced-rebuilt';
+          } else {
+            const priorFileId = state.fileId;
+            this._consumeHeader(state, header);
+            if (state.fileId !== priorFileId) {
+              rebuild = true;
+              reason = 'history-replaced-rebuilt';
+            }
+          }
+        }
+        if (rebuild) {
+          state.index = new NativeTaskHistoryIndex({ ...this._scope });
+          state.fileId = null;
+          state.indexedBytes = 0;
+          state.incomplete = new Set();
+          state.diagnostics = [];
+          this._diag(state, reason, { previousIndexedBytes: priorBytes });
+        }
+      }
+      state.dev = opened.dev;
+      state.ino = opened.ino;
+      await this._scanFrom(state, handle);
+      const done = await handle.stat();
+      state.fileSize = done.size;
+      state.mtimeMs = done.mtimeMs;
+      state.dev = done.dev;
+      state.ino = done.ino;
+      state.scanned = true;
+    } catch (error) {
+      state.scanned = false;
+      if (error && typeof error.status === 'number') throw error;
+      fail('HISTORY_SCAN_FAULT', 500, 'history file scan failed');
+    } finally {
+      if (handle) await handle.close().catch(() => {});
+    }
+  }
+
+  async _readHeaderLine(handle) {
+    const probe = Buffer.alloc(HEADER_PROBE_BYTES);
+    const { bytesRead } = await handle.read(probe, 0, probe.length, 0);
+    const nl = probe.subarray(0, bytesRead).indexOf(0x0A);
+    if (nl === -1) return null;
+    return probe.subarray(0, nl + 1);
+  }
+
+  async _scanFrom(state, handle) {
+    const chunk = Buffer.alloc(SCAN_CHUNK_BYTES);
+    let position = state.indexedBytes;
+    let carry = null;
+    let carryStart = position;
+    let carryDropped = false;
+    for (;;) {
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+      if (bytesRead <= 0) break;
+      let cursor = 0;
+      for (;;) {
+        const nl = chunk.indexOf(0x0A, cursor);
+        if (nl === -1 || nl >= bytesRead) break;
+        const endOffset = position + nl + 1;
+        const offset = carry !== null ? carryStart : position + cursor;
+        let lineBuffer = null;
+        if (carry !== null && !carryDropped) {
+          const tail = chunk.subarray(cursor, nl + 1);
+          lineBuffer = Buffer.concat([carry, tail], carry.length + tail.length);
+        } else if (carry === null) {
+          lineBuffer = chunk.subarray(cursor, nl + 1);
+        }
+        if (lineBuffer !== null && lineBuffer.length <= MAX_ROW_BYTES) {
+          this._consumeLine(state, offset, endOffset, lineBuffer);
+        } else {
+          if (offset === 0) fail('HISTORY_HEADER_INVALID', 400, 'history file does not begin with a valid workbench-history/v1 header');
+          this._diag(state, 'scan-oversized-row', { offset, bytes: lineBuffer === null ? null : lineBuffer.length });
+          state.incomplete.add('oversized-row');
+        }
+        carry = null;
+        carryDropped = false;
+        cursor = nl + 1;
+      }
+      if (cursor < bytesRead) {
+        const rest = Buffer.from(chunk.subarray(cursor, bytesRead));
+        if (carry !== null) {
+          if (carryDropped || carry.length + rest.length > MAX_ROW_BYTES) {
+            if (!carryDropped) {
+              this._diag(state, 'scan-oversized-row', { offset: carryStart, bytes: carry.length + rest.length });
+              state.incomplete.add('oversized-row');
+            }
+            carryDropped = true;
+            carry = null;
+          } else {
+            carry = Buffer.concat([carry, rest], carry.length + rest.length);
+          }
+        } else if (rest.length > MAX_ROW_BYTES) {
+          this._diag(state, 'scan-oversized-row', { offset: carryStart, bytes: rest.length });
+          state.incomplete.add('oversized-row');
+          carryDropped = true;
+          carry = null;
+        } else {
+          carry = rest;
+          carryStart = position + cursor;
+        }
+      }
+      position += bytesRead;
+    }
+    if (carry !== null || carryDropped) {
+      if (carry !== null) state.incomplete.add('unfinished-tail');
+      state.indexedBytes = carryStart;
+    } else {
+      state.indexedBytes = position;
+    }
+  }
+
+  _consumeLine(state, offset, endOffset, lineBuffer) {
+    if (offset === 0) {
+      this._consumeHeader(state, lineBuffer);
+      return;
+    }
+    const event = this._parseLine(state, offset, lineBuffer);
+    if (event === null) return;
+    if (event.type === 'workbench/history-checkpoint') return;
+    if (event.type === 'workbench/history-gap') {
+      state.incomplete.add('history-gap');
+      return;
+    }
+    state.index.observe({ offset, endOffset, event });
+  }
+
+  _consumeHeader(state, lineBuffer) {
+    const header = this._parseLine(state, 0, lineBuffer);
+    if (header === null || header.schema !== HISTORY_SCHEMA || !isId(header.sessionId) || !isId(header.contextId)) {
+      fail('HISTORY_HEADER_INVALID', 400, 'history file does not begin with a valid workbench-history/v1 header');
+    }
+    if (header.sessionId !== this._scope.parentSessionId || header.contextId !== this._scope.contextId) {
+      fail('HISTORY_OWNERSHIP_MISMATCH', 409, 'history file belongs to a different session scope');
+    }
+    state.fileId = isId(header.fileId) ? header.fileId : null;
+    if (header.incomplete === true) state.incomplete.add('header-incomplete');
+  }
+
+  _parseLine(state, offset, lineBuffer) {
+    let end = lineBuffer.length;
+    if (end > 0 && lineBuffer[end - 1] === 0x0A) end--;
+    if (end > 0 && lineBuffer[end - 1] === 0x0D) end--;
+    let parsed = null;
+    try { parsed = JSON.parse(lineBuffer.toString('utf8', 0, end)); } catch (error) { parsed = null; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      this._diag(state, 'scan-corrupt-row', { offset });
+      state.incomplete.add('corrupt-row');
+      return null;
+    }
+    return parsed;
+  }
+
+  _diag(state, code, ids) {
+    if (state.diagnostics.length >= READER_DIAGNOSTIC_CAP) return;
+    state.diagnostics.push(Object.assign({ code }, ids || {}));
+  }
+
+  _diagnosticView(state) {
+    const own = state.diagnostics.map(item => Object.assign({}, item, { source: 'reader' }));
+    const indexed = state.index.diagnostics().map(item => Object.assign({}, item, { source: 'index' }));
+    const all = own.concat(indexed);
+    return {
+      items: all.slice(0, RESPONSE_DIAGNOSTIC_CAP),
+      total: all.length,
+      truncated: all.length > RESPONSE_DIAGNOSTIC_CAP,
+    };
+  }
+}
+
+function nativeTaskHistoryCacheStats() {
+  const readers = [];
+  for (const entry of readerCache.values()) {
+    const state = entry.state;
+    if (!state) continue;
+    readers.push({
+      file: state.file,
+      scope: state.scope,
+      fileId: state.fileId,
+      fileSize: state.fileSize,
+      indexedBytes: state.indexedBytes,
+      incomplete: [...state.incomplete],
+      index: state.index.stats(),
+    });
+  }
+  return { entries: readerCache.size, maxEntries: CACHE_MAX_READERS, readers };
+}
+
+function createNativeTaskHistoryReader(options) { return new NativeTaskHistoryReader(options); }
+
+module.exports = {
+  NativeTaskHistoryReader,
+  createNativeTaskHistoryReader,
+  nativeTaskHistoryCacheStats,
+  NATIVE_TASK_HISTORY_READER_LIMITS: Object.freeze({
+    defaultLimit: DEFAULT_LIMIT,
+    maxLimit: MAX_LIMIT,
+    maxPageBytes: MAX_PAGE_BYTES,
+    maxRowBytes: MAX_ROW_BYTES,
+    scanChunkBytes: SCAN_CHUNK_BYTES,
+    maxCursorChars: MAX_CURSOR_CHARS,
+  }),
+};