@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/packages/server/lib/session-history.js

@@ -1,612 +1,612 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-
-const HEADER = 'workbench-history/v1';
-const DELTAS = new Set(['claude/text-delta', 'claude/thinking-delta']);
-
-// Rows that carry native task facts are evidence, not chat cache: archives
-// containing them may not be overwritten by wholesale recovery.
-function isNativeFactType(type) {
-  return type === 'claude/native-trace' || type === 'claude/native-task-state' || type === 'claude/native-task-transcript';
-}
-
-function parseLine(text) {
-  try { return JSON.parse(text); }
-  catch { throw Object.assign(new Error('会话历史文件损坏，原文件已保留。'), { status: 503, code: 'HISTORY_CORRUPT' }); }
-}
-
-function compactInto(events, event) {
-  const previous = events[events.length - 1];
-  if (previous && DELTAS.has(event.type) && previous.type === event.type && previous.id === event.id) {
-    previous.text = String(previous.text || '') + String(event.text || '');
-    // Provenance for later recovery: a merged row spans from its first
-    // fragment's sequence, so a stale partial buffer can be told to replace
-    // its fragments with the row instead of concatenating onto it.
-    if (previous.compactFrom === undefined) previous.compactFrom = previous.sequence;
-    previous.sequence = event.sequence;
-    return;
-  }
-  events.push({ ...event });
-}
-
-// Read backwards in byte chunks, not by loading every previous turn into RAM.
-// Buffer boundaries can bisect UTF-8 characters, so decode only complete lines.
-function* reverseLines(fd, end) {
-  let position = end;
-  let carry = Buffer.alloc(0);
-  while (position > 0) {
-    const start = Math.max(0, position - 65536);
-    const chunk = Buffer.alloc(position - start);
-    fs.readSync(fd, chunk, 0, chunk.length, start);
-    const data = Buffer.concat([chunk, carry]);
-    let lineEnd = data.length;
-    for (let i = data.length - 1; i >= 0; i--) {
-      if (data[i] !== 10) continue;
-      if (i + 1 < lineEnd) yield { offset: start + i + 1, text: data.subarray(i + 1, lineEnd).toString('utf8') };
-      lineEnd = i;
-    }
-    if (start === 0 && lineEnd > 0) yield { offset: 0, text: data.subarray(0, lineEnd).toString('utf8') };
-    carry = data.subarray(0, lineEnd);
-    position = start;
-  }
-}
-
-class SessionHistory {
-  constructor({ file, sessionId, contextId, startedAt, incomplete = false, onError }) {
-    this.file = file;
-    this.sessionId = sessionId;
-    this.contextId = contextId;
-    this.startedAt = startedAt || new Date().toISOString();
-    this.incomplete = incomplete;
-    this.onError = onError || (() => {});
-    this.highWater = 0;
-    this.pending = [];
-    this.timer = null;
-    this.error = null;
-    this.exists = false;
-    // Ordered failure lockout: once a durable batch (or a recovery-gap
-    // marker) fails to land, no newer row may raise the high-water mark past
-    // the failure head - neither plain batched rows nor later durable facts.
-    // The failed batch itself is retained verbatim for an in-place retry.
-    this.durableBarrier = null;
-    this.failedBatch = null;
-    // Generation identity is additive: v1 archives simply keep null.
-    this.fileId = null;
-    this.createdAt = null;
-    this.recoveryGap = null;
-    this.gapRecorded = null;
-    if (!fs.existsSync(file)) return;
-    const stat = fs.lstatSync(file);
-    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('会话历史路径不是普通文件。');
-    const fd = fs.openSync(file, 'r');
-    try {
-      const head = Buffer.alloc(Math.min(stat.size, 4096));
-      fs.readSync(fd, head, 0, head.length, 0);
-      const header = parseLine(head.toString('utf8').split('\n')[0]);
-      if (header.schema !== HEADER || header.sessionId !== sessionId || header.contextId !== contextId) throw new Error('会话历史归属不匹配。');
-      this.incomplete = header.incomplete === true;
-      this.fileId = header.fileId || null;
-      this.createdAt = header.createdAt || null;
-      this.exists = true;
-      // The high-water mark is the highest sequence the file ever
-      // journaled, so a trailing legacy checkpoint that lowered the mark can
-      // never license re-minting a number an earlier row already owns, and a
-      // persisted recovery-gap marker survives the reopen instead of letting
-      // a known hole pass as completeness. The marker is honored unless
-      // every sequence in its interval is present again on disk — refills
-      // are journaled after the marker, so it is located first (a short
-      // backward pass: markers sit near the crash point) before the
-      // numbering scan counts coverage.
-      let gap = null;
-      for (const line of reverseLines(fd, stat.size)) {
-        const item = parseLine(line.text);
-        if (item.schema === HEADER) break;
-        if (item.type === 'workbench/history-gap') {
-          gap = { from: Number(item.from) || 0, to: Number(item.to) || 0, sessionId: item.sessionId || sessionId };
-          break;
-        }
-      }
-      let highest = 0;
-      const covered = new Set();
-      // A verifiably huge interval is not cheaply checkable for refill; it
-      // stays marked rather than risking a false heal.
-      const gapVerifiable = Boolean(gap) && gap.from > 0 && gap.to >= gap.from && gap.to - gap.from <= 1_000_000;
-      for (const line of reverseLines(fd, stat.size)) {
-        const item = parseLine(line.text);
-        if (item.schema === HEADER) break;
-        if (item.type === 'workbench/history-gap') continue;
-        const own = Number(item.streamSequence ?? item.sequence);
-        if (Number.isSafeInteger(own) && own > 0 && own > highest) highest = own;
-        // Coverage counts unique event sequences only. A checkpoint is a
-        // counter position, not an event: it may raise the restored mark
-        // (numbers the counter consumed without journaling rows) but it
-        // proves no content exists and therefore fills no hole. Duplicate
-        // rows collapse onto one sequence each.
-        if (!gapVerifiable || item.type === 'workbench/history-checkpoint') continue;
-        const sequence = Number(item.sequence);
-        if (!Number.isSafeInteger(sequence) || sequence <= 0) continue;
-        // A merged delta row carries its whole fragment run: compactFrom is
-        // stamped only when real fragments with those sequences were folded
-        // into this row's text, so every sequence in the span is provably
-        // present by content.
-        const spanFrom = Number.isSafeInteger(item.compactFrom) && item.compactFrom > 0 && item.compactFrom <= sequence
-          ? item.compactFrom : sequence;
-        for (let at = Math.max(spanFrom, gap.from); at <= Math.min(sequence, gap.to); at++) covered.add(at);
-      }
-      this.highWater = highest;
-      if (gap && gap.from > 0 && gap.to >= gap.from) {
-        let healed = gapVerifiable;
-        for (let at = gap.from; at <= gap.to && healed; at++) if (!covered.has(at)) healed = false;
-        if (!healed) {
-          this.recoveryGap = gap;
-          this.gapRecorded = { from: gap.from, to: gap.to };
-        }
-      }
-    } finally { fs.closeSync(fd); }
-  }
-
-  append(event) {
-    // A legal counter is a positive safe integer; anything else is unstamped
-    // and mints the next forward slot instead of a coercible oddity.
-    const provided = Number(event.sequence);
-    const sequence = Number.isSafeInteger(provided) && provided > 0 ? provided : this.highWater + 1;
-    if (sequence <= this.highWater) return;
-    if (this.durableBarrier) {
-      // Frozen behind a failed durable head: the row stays queued in
-      // arrival order, but the in-memory mark must not advance - a raised
-      // mark would let later dedupe or retry logic treat the hole as
-      // already journaled.
-      compactInto(this.pending, { ...event, at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence });
-      if (!this.timer) {
-        this.timer = setTimeout(() => { this.timer = null; this.flush(); }, 250);
-        this.timer.unref?.();
-      }
-      return;
-    }
-    this.highWater = sequence;
-    compactInto(this.pending, { ...event, at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence });
-    if (['claude/result', 'claude/aborted', 'claude/error', 'claude/turn-end'].includes(event.type)
-      || (event.type === 'claude/state' && ['idle', 'failed', 'aborted'].includes(event.state))) this.flush();
-    else if (!this.timer) {
-      this.timer = setTimeout(() => { this.timer = null; this.flush(); }, 250);
-      this.timer.unref?.();
-    }
-  }
-
-  _newHeader() {
-    return {
-      schema: HEADER, sessionId: this.sessionId, contextId: this.contextId, incomplete: this.incomplete,
-      fileId: crypto.randomUUID(), createdAt: new Date().toISOString(),
-    };
-  }
-
-  // Durable receipt path for facts that must be proven on disk before
-  // anything is built on them. Success is returned only after write AND
-  // fsync; a failure reports its exact phase, rolls the file back to the
-  // last complete row, keeps prior rows and the plain-append pending queue
-  // intact, and never advances the high-water mark. The counter is strictly
-  // forward: sequences at or below the mark are rejected, not silently
-  // dropped or re-minted.
-  appendDurable(events) {
-    if (!Array.isArray(events) || events.length === 0) {
-      return { ok: false, phase: 'input', error: 'appendDurable requires a non-empty events array', highWater: this.highWater };
-    }
-    if (this.durableBarrier) {
-      // A failed head owns the next journal position: newer durable facts
-      // are refused instead of silently raising the mark over the hole.
-      // The retained batch is retried only through retryFailedBatch().
-      return { ok: false, phase: 'frozen', error: `journal is frozen behind failed sequence ${this.durableBarrier.sequence}`, highWater: this.highWater, pendingCount: this.pending.length };
-    }
-    const staged = [];
-    for (const event of events) {
-      const sequence = Number(event && event.sequence);
-      if (!event || typeof event !== 'object' || !Number.isSafeInteger(sequence) || sequence <= this.highWater) {
-        return { ok: false, phase: 'sequence', error: `sequence ${event && event.sequence} is not ahead of high-water ${this.highWater}`, highWater: this.highWater, pendingCount: this.pending.length };
-      }
-      // The staged row is an OWNED deep copy taken before any write attempt:
-      // a retained failed batch must replay the fact as first submitted, not
-      // whatever the caller (or an onError hook re-entering during the
-      // failure) later mutates in nested payload objects. A JSON round-trip
-      // is the file's own serialization semantics; anything it cannot
-      // express is refused with a fixed code that leaks no field content.
-      let own;
-      try {
-        own = JSON.parse(JSON.stringify(event));
-      } catch {
-        return { ok: false, phase: 'input', error: 'HISTORY_FACT_NOT_SERIALIZABLE', highWater: this.highWater, pendingCount: this.pending.length };
-      }
-      staged.push(Object.assign(own, { at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence }));
-    }
-    for (let i = 1; i < staged.length; i++) {
-      if (staged[i].sequence <= staged[i - 1].sequence) {
-        return { ok: false, phase: 'sequence', error: 'appendDurable batch sequences must strictly increase', highWater: this.highWater, pendingCount: this.pending.length };
-      }
-    }
-    const receipt = this._commitDurableRows(staged);
-    if (receipt.ok) this.highWater = staged[staged.length - 1].sequence;
-    else this._retainFailedBatch(staged, receipt.phase);
-    return receipt.ok
-      ? { ...receipt, sequence: this.highWater, highWater: this.highWater }
-      : { ...receipt, highWater: this.highWater };
-  }
-
-  // Retain the exact staged batch that failed so the same facts keep their
-  // original sequences for an in-place retry; the barrier head is the
-  // batch's first sequence. Nothing is cleared here - only a successful
-  // retry (or an explicitly recorded gap at close) may move past it.
-  _retainFailedBatch(staged, phase) {
-    if (!this.failedBatch) this.failedBatch = staged;
-    if (!this.durableBarrier) this.durableBarrier = { sequence: staged[0].sequence, phase: phase || 'write' };
-  }
-
-  // Same-batch, same-sequence retry of the retained failure. Success lands
-  // exactly the original rows once (the forward-only counter and the
-  // rollback guarantee no duplicate), clears the barrier and lets the
-  // frozen plain rows flush on the next flush(); failure keeps everything
-  // retryable and the file untouched past the last complete row.
-  retryFailedBatch() {
-    if (!this.failedBatch) return { ok: true, phase: 'none', highWater: this.highWater };
-    const staged = this.failedBatch;
-    const receipt = this._commitDurableRows(staged);
-    if (receipt.ok) {
-      this.highWater = Math.max(this.highWater, staged[staged.length - 1].sequence);
-      this.failedBatch = null;
-      this.durableBarrier = null;
-      return { ...receipt, sequence: this.highWater, highWater: this.highWater };
-    }
-    this.durableBarrier = this.durableBarrier || { sequence: staged[0].sequence, phase: receipt.phase };
-    return { ...receipt, highWater: this.highWater };
-  }
-
-  // Shared durable journal core: land any queued plain rows that sit BELOW
-  // the staged head first so the file stays arrival-ordered (a ceiling keeps
-  // rows above a barrier frozen), then write+fsync the staged rows in one
-  // 'r+' positioned write with half-line rollback. A stale error with
-  // nothing still queued below does not veto the attempt: the receipt
-  // itself is the retry, and a successful write+fsync clears it. A failed
-  // receipt leaves prior rows and the pending queue intact.
-  _commitDurableRows(staged) {
-    this.flush(staged[0].sequence);
-    // Out-of-order guard: a stale error only vetoes the attempt when rows
-    // that belong BELOW the staged head could not be landed - writing the
-    // staged batch past them would break arrival order. Frozen rows above
-    // the head are the barrier's business, not this write's.
-    const head = staged[0].sequence;
-    const blockedBelow = this.pending.some(row => {
-      const own = Number(row.streamSequence ?? row.sequence);
-      return !Number.isSafeInteger(own) || own < head;
-    });
-    if (this.error && blockedBelow) return { ok: false, phase: 'journal', error: this.error, pendingCount: this.pending.length };
-    let fd, start;
-    try {
-      fs.mkdirSync(path.dirname(this.file), { recursive: true });
-      if (!this.exists) {
-        const header = this._newHeader();
-        fs.writeFileSync(this.file, `${JSON.stringify(header)}\n`, { flag: 'wx', mode: 0o600 });
-        this.exists = true;
-        this.fileId = header.fileId;
-        this.createdAt = header.createdAt;
-      }
-      const payload = Buffer.from(staged.map(event => JSON.stringify(event)).join('\n') + '\n');
-      // 'r+' with explicit positions, not append mode: Windows refuses
-      // ftruncate on O_APPEND handles, which would turn the half-line
-      // rollback below into a silent no-op.
-      fd = fs.openSync(this.file, 'r+', 0o600);
-      start = fs.fstatSync(fd).size;
-      let written = 0;
-      while (written < payload.length) {
-        const count = fs.writeSync(fd, payload, written, payload.length - written, start + written);
-        if (!count) throw Object.assign(new Error('history write made no progress'), { code: 'EIO' });
-        written += count;
-      }
-      try { fs.fsyncSync(fd); } catch (fsyncError) { fsyncError.durablePhase = 'fsync'; throw fsyncError; }
-      this.error = null;
-      return { ok: true, phase: 'committed', count: staged.length, bytes: payload.length };
-    } catch (error) {
-      // No half line and no unproven durable row may survive a failed
-      // receipt; the rollback keeps every prior complete row so a retry
-      // rewrites exactly the failed batch.
-      if (fd !== undefined && start !== undefined) { try { fs.ftruncateSync(fd, start); } catch { /* rollback best effort; error state below still blocks reads */ } }
-      this.error = error.code || 'HISTORY_DURABLE_WRITE_FAILED';
-      this.onError(error);
-      return { ok: false, phase: error.durablePhase === 'fsync' ? 'fsync' : 'write', error: error.message, code: error.code || null, pendingCount: this.pending.length };
-    } finally { if (fd !== undefined) fs.closeSync(fd); }
-  }
-
-  // Bounded backward scan of the durable archive: the newest rows inside
-  // (afterSequence, beforeSequence), at most maxLines of them, without the
-  // file ever being resident in memory. `complete` is true only when the
-  // page provably covers every durable row in that window (the scan crossed
-  // the lower boundary or hit the header) and no mixed numbering-era row
-  // was met; a page capped by maxLines reports truncated with
-  // nextBeforeSequence so callers page towards the past instead of
-  // re-reading the newest rows. Never returns an empty page as a stand-in
-  // for a complete archive.
-  durableTail({ afterSequence = 0, maxLines = 5000, beforeSequence } = {}) {
-    const after = Number(afterSequence);
-    const cap = Number(maxLines);
-    const before = beforeSequence === undefined || beforeSequence === null ? Number.POSITIVE_INFINITY : Number(beforeSequence);
-    if (!Number.isFinite(after) || after < 0) throw Object.assign(new Error('afterSequence must be a non-negative number'), { status: 400 });
-    if (Number.isNaN(before)) throw Object.assign(new Error('beforeSequence must be a number'), { status: 400 });
-    if (before <= after) throw Object.assign(new Error('beforeSequence must be greater than afterSequence'), { status: 400 });
-    if (!Number.isInteger(cap) || cap < 1 || cap > 20000) throw Object.assign(new Error('maxLines must be between 1 and 20000'), { status: 400 });
-    this.flush();
-    if (this.error) throw Object.assign(new Error('会话历史写入失败，请检查磁盘与本地日志。'), { status: 503, code: this.error });
-    if (!this.exists) return { events: [], complete: true, truncated: false, fromSequence: null, toSequence: null, nextBeforeSequence: null, highWater: this.highWater, incomplete: this.incomplete };
-    const fd = fs.openSync(this.file, 'r');
-    const collected = [];
-    let hitBoundary = false, mixedEra = false, smallest = null, largest = null;
-    try {
-      const size = fs.fstatSync(fd).size;
-      for (const line of reverseLines(fd, size)) {
-        const event = parseLine(line.text);
-        if (event.schema === HEADER) { hitBoundary = true; break; }
-        if (event.type === 'workbench/history-checkpoint') { mixedEra = true; continue; }
-        // A gap marker is known control metadata, not a mixed-numbering-era
-        // row: the hole it declares is reported separately via recoveryGap.
-        if (event.type === 'workbench/history-gap') continue;
-        const sequence = Number(event.sequence);
-        if (!Number.isFinite(sequence) || sequence <= 0) { mixedEra = true; continue; }
-        if (sequence <= after) { hitBoundary = true; break; }
-        if (sequence >= before) continue;
-        if (collected.length >= cap) break;
-        collected.push(event);
-        smallest = sequence;
-        if (largest === null) largest = sequence;
-      }
-    } finally { fs.closeSync(fd); }
-    const truncated = !hitBoundary;
-    return {
-      events: collected.reverse(),
-      complete: hitBoundary && !mixedEra,
-      truncated,
-      fromSequence: smallest,
-      toSequence: largest,
-      nextBeforeSequence: truncated && smallest !== null ? smallest : null,
-      highWater: this.highWater,
-      incomplete: this.incomplete,
-    };
-  }
-
-  // Exact lookup of one committed numbered row, scanned backwards with an
-  // early exit: rows arrive in ascending order, so the first row numbered
-  // below the target proves the target absent. Returns null when the row
-  // cannot be proven present.
-  durableRow(sequence) {
-    const target = Number(sequence);
-    if (!Number.isSafeInteger(target) || target <= 0 || !this.exists) return null;
-    const fd = fs.openSync(this.file, 'r');
-    try {
-      for (const line of reverseLines(fd, fs.fstatSync(fd).size)) {
-        const item = parseLine(line.text);
-        if (item.schema === HEADER) break;
-        if (item.type === 'workbench/history-checkpoint' || item.type === 'workbench/history-gap') continue;
-        const own = Number(item.sequence);
-        if (own === target) return item;
-        if (Number.isSafeInteger(own) && own < target) break;
-      }
-    } finally { fs.closeSync(fd); }
-    return null;
-  }
-
-  // The recovery gap is control metadata in the journal's own row space and
-  // earns the same receipt contract as durable facts: the marker counts as
-  // recorded only after a proven write+fsync, so a failed write keeps the
-  // original rows and a retryable state instead of silently skipping the
-  // marker on a later call. The interval is rewritten only when it changes.
-  recordRecoveryGap(from, to) {
-    const start = Number(from), end = Number(to);
-    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start <= 0 || end < start) {
-      return { ok: false, phase: 'input', highWater: this.highWater };
-    }
-    this.recoveryGap = { from: start, to: end, sessionId: this.sessionId };
-    if (this.gapRecorded && this.gapRecorded.from === start && this.gapRecorded.to === end) {
-      return { ok: true, phase: 'already-recorded', highWater: this.highWater };
-    }
-    // The marker is control metadata, not a native fact: its failed receipt
-    // is diagnosed through the return value and onError, but it must not
-    // raise the sticky read veto - readers keep serving with the in-memory
-    // gap instead of losing the whole journal to a metadata write.
-    const priorError = this.error;
-    const receipt = this._commitDurableRows([{ type: 'workbench/history-gap', from: start, to: end, sessionId: this.sessionId }]);
-    if (!receipt.ok) this.error = priorError;
-    if (receipt.ok) {
-      this.gapRecorded = { from: start, to: end };
-      // A landed marker declares the hole honestly; rows above the interval
-      // may flush again. The retained failed batch (if any) stays retained:
-      // its sequences sit inside the interval and belong to a retry.
-      if (this.durableBarrier && this.durableBarrier.phase === 'gap-marker') this.durableBarrier = null;
-    } else if (!this.durableBarrier) {
-      // While the marker itself cannot be proven on disk, no plain row may
-      // flush past the unrecorded hole either.
-      this.durableBarrier = { sequence: start, phase: 'gap-marker' };
-    }
-    return { ...receipt, highWater: this.highWater };
-  }
-
-  containsNativeFacts() {
-    if (!this.exists) return false;
-    const fd = fs.openSync(this.file, 'r');
-    try {
-      for (const line of reverseLines(fd, fs.fstatSync(fd).size)) {
-        if (!line.text.includes('"claude/native-')) continue;
-        if (isNativeFactType(parseLine(line.text).type)) return true;
-      }
-    } finally { fs.closeSync(fd); }
-    return false;
-  }
-
-  seedRecovered(events, streamSequence) {
-    // A valid-but-incomplete archive that already carries native facts is
-    // collected evidence: replacing it with a recovered chat transcript
-    // would destroy task rows no other source can rebuild. Keep the file
-    // and the incomplete flag; the refusal is an explicit receipt.
-    if (this.exists && this.containsNativeFacts()) {
-      this.incomplete = true;
-      const refusal = Object.assign(new Error('会话历史含原生任务事实，拒绝恢复覆盖；原文件已保留。'), { code: 'HISTORY_NATIVE_FACTS_REFUSED' });
-      this.onError(refusal);
-      return { ok: false, refused: true, reason: 'native-facts', highWater: this.highWater };
-    }
-    const recovered = [];
-    for (const event of events) compactInto(recovered, { ...event, at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence: 0 });
-    recovered.push({ type: 'workbench/history-checkpoint', streamSequence });
-    const header = { schema: HEADER, sessionId: this.sessionId, contextId: this.contextId, incomplete: false, fileId: crypto.randomUUID(), createdAt: new Date().toISOString() };
-    const temporary = `${this.file}.${process.pid}.${crypto.randomUUID()}.recovery.tmp`;
-    try {
-      fs.mkdirSync(path.dirname(this.file), { recursive: true });
-      fs.writeFileSync(temporary, [header, ...recovered].map(item => JSON.stringify(item)).join('\n') + '\n', { mode: 0o600, flag: 'wx' });
-      fs.renameSync(temporary, this.file);
-      this.pending = []; this.highWater = streamSequence; this.incomplete = false; this.exists = true; this.error = null;
-      this.fileId = header.fileId; this.createdAt = header.createdAt;
-      return { ok: true, refused: false, highWater: this.highWater };
-    } catch (error) {
-      this.onError(error);
-      return { ok: false, refused: false, error: error.message, code: error.code || null, highWater: this.highWater };
-    } finally { try { fs.unlinkSync(temporary); } catch {} }
-  }
-
-  // Forward-only: a checkpoint may raise the mark (numbers the counter
-  // consumed without journaling rows) but may never lower it — old rows
-  // keep their numbering and nothing re-mints a sequence the archive
-  // already holds. A frozen journal refuses: the mark must not jump a
-  // failed head, and the checkpoint row would flush above the barrier.
-  resetStreamSequence(streamSequence) {
-    const target = Number(streamSequence);
-    if (!Number.isSafeInteger(target) || target <= this.highWater) return false;
-    if (this.durableBarrier) return false;
-    this.highWater = target;
-    this.pending.push({ type: 'workbench/history-checkpoint', streamSequence: target });
-    this.flush();
-    return true;
-  }
-
-  // Land queued plain rows. Without a ceiling the call is a free flush: it
-  // is refused while a durable barrier is armed (rows above a failed head
-  // must never reach the file first) and re-arms the timer so an unfrozen
-  // journal drains later. A ceiling (the staged head of a durable commit)
-  // lands only the rows that sit below it, keeping arrival order even
-  // during a retry of the retained failed batch. Rows queued while frozen
-  // never raised the in-memory mark, so a successful flush adopts the
-  // highest written sequence instead.
-  flush(ceiling) {
-    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
-    const limit = Number.isSafeInteger(ceiling) && ceiling > 0 ? ceiling : null;
-    if (this.durableBarrier && limit === null) {
-      if (this.pending.length && !this.timer) {
-        this.timer = setTimeout(() => { this.timer = null; this.flush(); }, 250);
-        this.timer.unref?.();
-      }
-      return;
-    }
-    if (!this.pending.length) return;
-    let rows = this.pending;
-    if (limit !== null) {
-      let split = rows.length;
-      for (let i = 0; i < rows.length; i++) {
-        const own = Number(rows[i].streamSequence ?? rows[i].sequence);
-        if (Number.isSafeInteger(own) && own >= limit) { split = i; break; }
-      }
-      if (split === 0) return;
-      rows = rows.slice(0, split);
-    }
-    let fd, start;
-    try {
-      fs.mkdirSync(path.dirname(this.file), { recursive: true });
-      if (!this.exists) {
-        const header = this._newHeader();
-        fs.writeFileSync(this.file, `${JSON.stringify(header)}\n`, { flag: 'wx', mode: 0o600 });
-        this.exists = true;
-        this.fileId = header.fileId;
-        this.createdAt = header.createdAt;
-      }
-      const payload = Buffer.from(rows.map(event => JSON.stringify(event)).join('\n') + '\n');
-      fd = fs.openSync(this.file, 'r+', 0o600);
-      start = fs.fstatSync(fd).size;
-      let written = 0;
-      while (written < payload.length) {
-        const count = fs.writeSync(fd, payload, written, payload.length - written, start + written);
-        if (!count) throw Object.assign(new Error('history write made no progress'), { code: 'EIO' });
-        written += count;
-      }
-      this.pending = this.pending.slice(rows.length);
-      let landed = 0;
-      for (const row of rows) {
-        const own = Number(row.streamSequence ?? row.sequence);
-        if (Number.isSafeInteger(own) && own > landed) landed = own;
-      }
-      if (landed > this.highWater) this.highWater = landed;
-      this.error = null;
-    } catch (error) {
-      // A failed append must not leave half a JSON line before the retry.
-      // This archive has one owning service/writer; prior complete rows stay intact.
-      if (fd !== undefined && start !== undefined) try { fs.ftruncateSync(fd, start); } catch {}
-      this.error = error.code || 'HISTORY_WRITE_FAILED';
-      this.onError(error);
-    } finally { if (fd !== undefined) fs.closeSync(fd); }
-  }
-
-  read({ before, limit = 20 } = {}) {
-    const count = Number(limit);
-    if (!Number.isInteger(count) || count < 1 || count > 100) throw Object.assign(new Error('limit must be between 1 and 100'), { status: 400 });
-    if (before !== undefined && before !== null && !/^[1-9]\d*$/.test(String(before))) throw Object.assign(new Error('invalid history cursor'), { status: 400 });
-    this.flush();
-    if (this.error) throw Object.assign(new Error('会话历史写入失败，请检查磁盘与本地日志。'), { status: 503, code: this.error });
-    if (!this.exists) return { events: [], nextCursor: null, incomplete: this.incomplete, highWater: this.highWater, ...(this.recoveryGap ? { recoveryGap: this.recoveryGap } : {}) };
-    const fd = fs.openSync(this.file, 'r');
-    const selected = [], prelude = [];
-    let cursor = null, prompts = 0;
-    try {
-      const size = fs.fstatSync(fd).size;
-      const end = before == null ? size : Number(before);
-      if (!Number.isSafeInteger(end) || end > size) throw Object.assign(new Error('invalid history cursor'), { status: 400 });
-      if (before != null) {
-        const previous = Buffer.alloc(1); fs.readSync(fd, previous, 0, 1, end - 1);
-        if (previous[0] !== 10) throw Object.assign(new Error('invalid history cursor'), { status: 400 });
-      }
-      let boundary = null;
-      for (const line of reverseLines(fd, end)) {
-        const event = parseLine(line.text);
-        if (event.schema === HEADER || event.type === 'workbench/history-checkpoint' || event.type === 'workbench/history-gap') continue;
-        if (prompts >= count) {
-          if (event.type === 'claude/user-prompt') { cursor = boundary; break; }
-          prelude.push(event);
-          continue;
-        }
-        selected.push(event);
-        if (event.type === 'claude/user-prompt') { prompts++; boundary = line.offset; }
-      }
-      if (cursor === null) selected.push(...prelude);
-    } finally { fs.closeSync(fd); }
-    const events = [];
-    for (const event of selected.reverse()) compactInto(events, event);
-    return { events, nextCursor: cursor === null ? null : String(cursor), incomplete: this.incomplete, highWater: this.highWater, ...(this.recoveryGap ? { recoveryGap: this.recoveryGap } : {}) };
-  }
-
-  // Shutdown contract for a journaled history: a retained failed batch is
-  // retried in place first; only if that still fails is the hole persisted
-  // as a recovery-gap marker (never the other way around - the queue is
-  // never cleared to fake a drain). A landed marker lets the frozen plain
-  // rows flush as an honest partial refill; a marker that cannot land
-  // leaves everything queued and the failure diagnosable.
-  close() {
-    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
-    if (this.failedBatch) {
-      const retried = this.retryFailedBatch();
-      if (!retried.ok) {
-        const head = this.failedBatch[0].sequence;
-        let ceiling = this.failedBatch[this.failedBatch.length - 1].sequence;
-        for (const row of this.pending) {
-          const own = Number(row.streamSequence ?? row.sequence);
-          if (Number.isSafeInteger(own) && own > ceiling) ceiling = own;
-        }
-        this.recordRecoveryGap(head, ceiling);
-      }
-    }
-    this.flush();
-  }
-}
-
-module.exports = { SessionHistory, compactInto, reverseLines };
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const HEADER = 'workbench-history/v1';
+const DELTAS = new Set(['claude/text-delta', 'claude/thinking-delta']);
+
+// Rows that carry native task facts are evidence, not chat cache: archives
+// containing them may not be overwritten by wholesale recovery.
+function isNativeFactType(type) {
+  return type === 'claude/native-trace' || type === 'claude/native-task-state' || type === 'claude/native-task-transcript';
+}
+
+function parseLine(text) {
+  try { return JSON.parse(text); }
+  catch { throw Object.assign(new Error('会话历史文件损坏，原文件已保留。'), { status: 503, code: 'HISTORY_CORRUPT' }); }
+}
+
+function compactInto(events, event) {
+  const previous = events[events.length - 1];
+  if (previous && DELTAS.has(event.type) && previous.type === event.type && previous.id === event.id) {
+    previous.text = String(previous.text || '') + String(event.text || '');
+    // Provenance for later recovery: a merged row spans from its first
+    // fragment's sequence, so a stale partial buffer can be told to replace
+    // its fragments with the row instead of concatenating onto it.
+    if (previous.compactFrom === undefined) previous.compactFrom = previous.sequence;
+    previous.sequence = event.sequence;
+    return;
+  }
+  events.push({ ...event });
+}
+
+// Read backwards in byte chunks, not by loading every previous turn into RAM.
+// Buffer boundaries can bisect UTF-8 characters, so decode only complete lines.
+function* reverseLines(fd, end) {
+  let position = end;
+  let carry = Buffer.alloc(0);
+  while (position > 0) {
+    const start = Math.max(0, position - 65536);
+    const chunk = Buffer.alloc(position - start);
+    fs.readSync(fd, chunk, 0, chunk.length, start);
+    const data = Buffer.concat([chunk, carry]);
+    let lineEnd = data.length;
+    for (let i = data.length - 1; i >= 0; i--) {
+      if (data[i] !== 10) continue;
+      if (i + 1 < lineEnd) yield { offset: start + i + 1, text: data.subarray(i + 1, lineEnd).toString('utf8') };
+      lineEnd = i;
+    }
+    if (start === 0 && lineEnd > 0) yield { offset: 0, text: data.subarray(0, lineEnd).toString('utf8') };
+    carry = data.subarray(0, lineEnd);
+    position = start;
+  }
+}
+
+class SessionHistory {
+  constructor({ file, sessionId, contextId, startedAt, incomplete = false, onError }) {
+    this.file = file;
+    this.sessionId = sessionId;
+    this.contextId = contextId;
+    this.startedAt = startedAt || new Date().toISOString();
+    this.incomplete = incomplete;
+    this.onError = onError || (() => {});
+    this.highWater = 0;
+    this.pending = [];
+    this.timer = null;
+    this.error = null;
+    this.exists = false;
+    // Ordered failure lockout: once a durable batch (or a recovery-gap
+    // marker) fails to land, no newer row may raise the high-water mark past
+    // the failure head - neither plain batched rows nor later durable facts.
+    // The failed batch itself is retained verbatim for an in-place retry.
+    this.durableBarrier = null;
+    this.failedBatch = null;
+    // Generation identity is additive: v1 archives simply keep null.
+    this.fileId = null;
+    this.createdAt = null;
+    this.recoveryGap = null;
+    this.gapRecorded = null;
+    if (!fs.existsSync(file)) return;
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('会话历史路径不是普通文件。');
+    const fd = fs.openSync(file, 'r');
+    try {
+      const head = Buffer.alloc(Math.min(stat.size, 4096));
+      fs.readSync(fd, head, 0, head.length, 0);
+      const header = parseLine(head.toString('utf8').split('\n')[0]);
+      if (header.schema !== HEADER || header.sessionId !== sessionId || header.contextId !== contextId) throw new Error('会话历史归属不匹配。');
+      this.incomplete = header.incomplete === true;
+      this.fileId = header.fileId || null;
+      this.createdAt = header.createdAt || null;
+      this.exists = true;
+      // The high-water mark is the highest sequence the file ever
+      // journaled, so a trailing legacy checkpoint that lowered the mark can
+      // never license re-minting a number an earlier row already owns, and a
+      // persisted recovery-gap marker survives the reopen instead of letting
+      // a known hole pass as completeness. The marker is honored unless
+      // every sequence in its interval is present again on disk — refills
+      // are journaled after the marker, so it is located first (a short
+      // backward pass: markers sit near the crash point) before the
+      // numbering scan counts coverage.
+      let gap = null;
+      for (const line of reverseLines(fd, stat.size)) {
+        const item = parseLine(line.text);
+        if (item.schema === HEADER) break;
+        if (item.type === 'workbench/history-gap') {
+          gap = { from: Number(item.from) || 0, to: Number(item.to) || 0, sessionId: item.sessionId || sessionId };
+          break;
+        }
+      }
+      let highest = 0;
+      const covered = new Set();
+      // A verifiably huge interval is not cheaply checkable for refill; it
+      // stays marked rather than risking a false heal.
+      const gapVerifiable = Boolean(gap) && gap.from > 0 && gap.to >= gap.from && gap.to - gap.from <= 1_000_000;
+      for (const line of reverseLines(fd, stat.size)) {
+        const item = parseLine(line.text);
+        if (item.schema === HEADER) break;
+        if (item.type === 'workbench/history-gap') continue;
+        const own = Number(item.streamSequence ?? item.sequence);
+        if (Number.isSafeInteger(own) && own > 0 && own > highest) highest = own;
+        // Coverage counts unique event sequences only. A checkpoint is a
+        // counter position, not an event: it may raise the restored mark
+        // (numbers the counter consumed without journaling rows) but it
+        // proves no content exists and therefore fills no hole. Duplicate
+        // rows collapse onto one sequence each.
+        if (!gapVerifiable || item.type === 'workbench/history-checkpoint') continue;
+        const sequence = Number(item.sequence);
+        if (!Number.isSafeInteger(sequence) || sequence <= 0) continue;
+        // A merged delta row carries its whole fragment run: compactFrom is
+        // stamped only when real fragments with those sequences were folded
+        // into this row's text, so every sequence in the span is provably
+        // present by content.
+        const spanFrom = Number.isSafeInteger(item.compactFrom) && item.compactFrom > 0 && item.compactFrom <= sequence
+          ? item.compactFrom : sequence;
+        for (let at = Math.max(spanFrom, gap.from); at <= Math.min(sequence, gap.to); at++) covered.add(at);
+      }
+      this.highWater = highest;
+      if (gap && gap.from > 0 && gap.to >= gap.from) {
+        let healed = gapVerifiable;
+        for (let at = gap.from; at <= gap.to && healed; at++) if (!covered.has(at)) healed = false;
+        if (!healed) {
+          this.recoveryGap = gap;
+          this.gapRecorded = { from: gap.from, to: gap.to };
+        }
+      }
+    } finally { fs.closeSync(fd); }
+  }
+
+  append(event) {
+    // A legal counter is a positive safe integer; anything else is unstamped
+    // and mints the next forward slot instead of a coercible oddity.
+    const provided = Number(event.sequence);
+    const sequence = Number.isSafeInteger(provided) && provided > 0 ? provided : this.highWater + 1;
+    if (sequence <= this.highWater) return;
+    if (this.durableBarrier) {
+      // Frozen behind a failed durable head: the row stays queued in
+      // arrival order, but the in-memory mark must not advance - a raised
+      // mark would let later dedupe or retry logic treat the hole as
+      // already journaled.
+      compactInto(this.pending, { ...event, at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence });
+      if (!this.timer) {
+        this.timer = setTimeout(() => { this.timer = null; this.flush(); }, 250);
+        this.timer.unref?.();
+      }
+      return;
+    }
+    this.highWater = sequence;
+    compactInto(this.pending, { ...event, at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence });
+    if (['claude/result', 'claude/aborted', 'claude/error', 'claude/turn-end'].includes(event.type)
+      || (event.type === 'claude/state' && ['idle', 'failed', 'aborted'].includes(event.state))) this.flush();
+    else if (!this.timer) {
+      this.timer = setTimeout(() => { this.timer = null; this.flush(); }, 250);
+      this.timer.unref?.();
+    }
+  }
+
+  _newHeader() {
+    return {
+      schema: HEADER, sessionId: this.sessionId, contextId: this.contextId, incomplete: this.incomplete,
+      fileId: crypto.randomUUID(), createdAt: new Date().toISOString(),
+    };
+  }
+
+  // Durable receipt path for facts that must be proven on disk before
+  // anything is built on them. Success is returned only after write AND
+  // fsync; a failure reports its exact phase, rolls the file back to the
+  // last complete row, keeps prior rows and the plain-append pending queue
+  // intact, and never advances the high-water mark. The counter is strictly
+  // forward: sequences at or below the mark are rejected, not silently
+  // dropped or re-minted.
+  appendDurable(events) {
+    if (!Array.isArray(events) || events.length === 0) {
+      return { ok: false, phase: 'input', error: 'appendDurable requires a non-empty events array', highWater: this.highWater };
+    }
+    if (this.durableBarrier) {
+      // A failed head owns the next journal position: newer durable facts
+      // are refused instead of silently raising the mark over the hole.
+      // The retained batch is retried only through retryFailedBatch().
+      return { ok: false, phase: 'frozen', error: `journal is frozen behind failed sequence ${this.durableBarrier.sequence}`, highWater: this.highWater, pendingCount: this.pending.length };
+    }
+    const staged = [];
+    for (const event of events) {
+      const sequence = Number(event && event.sequence);
+      if (!event || typeof event !== 'object' || !Number.isSafeInteger(sequence) || sequence <= this.highWater) {
+        return { ok: false, phase: 'sequence', error: `sequence ${event && event.sequence} is not ahead of high-water ${this.highWater}`, highWater: this.highWater, pendingCount: this.pending.length };
+      }
+      // The staged row is an OWNED deep copy taken before any write attempt:
+      // a retained failed batch must replay the fact as first submitted, not
+      // whatever the caller (or an onError hook re-entering during the
+      // failure) later mutates in nested payload objects. A JSON round-trip
+      // is the file's own serialization semantics; anything it cannot
+      // express is refused with a fixed code that leaks no field content.
+      let own;
+      try {
+        own = JSON.parse(JSON.stringify(event));
+      } catch {
+        return { ok: false, phase: 'input', error: 'HISTORY_FACT_NOT_SERIALIZABLE', highWater: this.highWater, pendingCount: this.pending.length };
+      }
+      staged.push(Object.assign(own, { at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence }));
+    }
+    for (let i = 1; i < staged.length; i++) {
+      if (staged[i].sequence <= staged[i - 1].sequence) {
+        return { ok: false, phase: 'sequence', error: 'appendDurable batch sequences must strictly increase', highWater: this.highWater, pendingCount: this.pending.length };
+      }
+    }
+    const receipt = this._commitDurableRows(staged);
+    if (receipt.ok) this.highWater = staged[staged.length - 1].sequence;
+    else this._retainFailedBatch(staged, receipt.phase);
+    return receipt.ok
+      ? { ...receipt, sequence: this.highWater, highWater: this.highWater }
+      : { ...receipt, highWater: this.highWater };
+  }
+
+  // Retain the exact staged batch that failed so the same facts keep their
+  // original sequences for an in-place retry; the barrier head is the
+  // batch's first sequence. Nothing is cleared here - only a successful
+  // retry (or an explicitly recorded gap at close) may move past it.
+  _retainFailedBatch(staged, phase) {
+    if (!this.failedBatch) this.failedBatch = staged;
+    if (!this.durableBarrier) this.durableBarrier = { sequence: staged[0].sequence, phase: phase || 'write' };
+  }
+
+  // Same-batch, same-sequence retry of the retained failure. Success lands
+  // exactly the original rows once (the forward-only counter and the
+  // rollback guarantee no duplicate), clears the barrier and lets the
+  // frozen plain rows flush on the next flush(); failure keeps everything
+  // retryable and the file untouched past the last complete row.
+  retryFailedBatch() {
+    if (!this.failedBatch) return { ok: true, phase: 'none', highWater: this.highWater };
+    const staged = this.failedBatch;
+    const receipt = this._commitDurableRows(staged);
+    if (receipt.ok) {
+      this.highWater = Math.max(this.highWater, staged[staged.length - 1].sequence);
+      this.failedBatch = null;
+      this.durableBarrier = null;
+      return { ...receipt, sequence: this.highWater, highWater: this.highWater };
+    }
+    this.durableBarrier = this.durableBarrier || { sequence: staged[0].sequence, phase: receipt.phase };
+    return { ...receipt, highWater: this.highWater };
+  }
+
+  // Shared durable journal core: land any queued plain rows that sit BELOW
+  // the staged head first so the file stays arrival-ordered (a ceiling keeps
+  // rows above a barrier frozen), then write+fsync the staged rows in one
+  // 'r+' positioned write with half-line rollback. A stale error with
+  // nothing still queued below does not veto the attempt: the receipt
+  // itself is the retry, and a successful write+fsync clears it. A failed
+  // receipt leaves prior rows and the pending queue intact.
+  _commitDurableRows(staged) {
+    this.flush(staged[0].sequence);
+    // Out-of-order guard: a stale error only vetoes the attempt when rows
+    // that belong BELOW the staged head could not be landed - writing the
+    // staged batch past them would break arrival order. Frozen rows above
+    // the head are the barrier's business, not this write's.
+    const head = staged[0].sequence;
+    const blockedBelow = this.pending.some(row => {
+      const own = Number(row.streamSequence ?? row.sequence);
+      return !Number.isSafeInteger(own) || own < head;
+    });
+    if (this.error && blockedBelow) return { ok: false, phase: 'journal', error: this.error, pendingCount: this.pending.length };
+    let fd, start;
+    try {
+      fs.mkdirSync(path.dirname(this.file), { recursive: true });
+      if (!this.exists) {
+        const header = this._newHeader();
+        fs.writeFileSync(this.file, `${JSON.stringify(header)}\n`, { flag: 'wx', mode: 0o600 });
+        this.exists = true;
+        this.fileId = header.fileId;
+        this.createdAt = header.createdAt;
+      }
+      const payload = Buffer.from(staged.map(event => JSON.stringify(event)).join('\n') + '\n');
+      // 'r+' with explicit positions, not append mode: Windows refuses
+      // ftruncate on O_APPEND handles, which would turn the half-line
+      // rollback below into a silent no-op.
+      fd = fs.openSync(this.file, 'r+', 0o600);
+      start = fs.fstatSync(fd).size;
+      let written = 0;
+      while (written < payload.length) {
+        const count = fs.writeSync(fd, payload, written, payload.length - written, start + written);
+        if (!count) throw Object.assign(new Error('history write made no progress'), { code: 'EIO' });
+        written += count;
+      }
+      try { fs.fsyncSync(fd); } catch (fsyncError) { fsyncError.durablePhase = 'fsync'; throw fsyncError; }
+      this.error = null;
+      return { ok: true, phase: 'committed', count: staged.length, bytes: payload.length };
+    } catch (error) {
+      // No half line and no unproven durable row may survive a failed
+      // receipt; the rollback keeps every prior complete row so a retry
+      // rewrites exactly the failed batch.
+      if (fd !== undefined && start !== undefined) { try { fs.ftruncateSync(fd, start); } catch { /* rollback best effort; error state below still blocks reads */ } }
+      this.error = error.code || 'HISTORY_DURABLE_WRITE_FAILED';
+      this.onError(error);
+      return { ok: false, phase: error.durablePhase === 'fsync' ? 'fsync' : 'write', error: error.message, code: error.code || null, pendingCount: this.pending.length };
+    } finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+
+  // Bounded backward scan of the durable archive: the newest rows inside
+  // (afterSequence, beforeSequence), at most maxLines of them, without the
+  // file ever being resident in memory. `complete` is true only when the
+  // page provably covers every durable row in that window (the scan crossed
+  // the lower boundary or hit the header) and no mixed numbering-era row
+  // was met; a page capped by maxLines reports truncated with
+  // nextBeforeSequence so callers page towards the past instead of
+  // re-reading the newest rows. Never returns an empty page as a stand-in
+  // for a complete archive.
+  durableTail({ afterSequence = 0, maxLines = 5000, beforeSequence } = {}) {
+    const after = Number(afterSequence);
+    const cap = Number(maxLines);
+    const before = beforeSequence === undefined || beforeSequence === null ? Number.POSITIVE_INFINITY : Number(beforeSequence);
+    if (!Number.isFinite(after) || after < 0) throw Object.assign(new Error('afterSequence must be a non-negative number'), { status: 400 });
+    if (Number.isNaN(before)) throw Object.assign(new Error('beforeSequence must be a number'), { status: 400 });
+    if (before <= after) throw Object.assign(new Error('beforeSequence must be greater than afterSequence'), { status: 400 });
+    if (!Number.isInteger(cap) || cap < 1 || cap > 20000) throw Object.assign(new Error('maxLines must be between 1 and 20000'), { status: 400 });
+    this.flush();
+    if (this.error) throw Object.assign(new Error('会话历史写入失败，请检查磁盘与本地日志。'), { status: 503, code: this.error });
+    if (!this.exists) return { events: [], complete: true, truncated: false, fromSequence: null, toSequence: null, nextBeforeSequence: null, highWater: this.highWater, incomplete: this.incomplete };
+    const fd = fs.openSync(this.file, 'r');
+    const collected = [];
+    let hitBoundary = false, mixedEra = false, smallest = null, largest = null;
+    try {
+      const size = fs.fstatSync(fd).size;
+      for (const line of reverseLines(fd, size)) {
+        const event = parseLine(line.text);
+        if (event.schema === HEADER) { hitBoundary = true; break; }
+        if (event.type === 'workbench/history-checkpoint') { mixedEra = true; continue; }
+        // A gap marker is known control metadata, not a mixed-numbering-era
+        // row: the hole it declares is reported separately via recoveryGap.
+        if (event.type === 'workbench/history-gap') continue;
+        const sequence = Number(event.sequence);
+        if (!Number.isFinite(sequence) || sequence <= 0) { mixedEra = true; continue; }
+        if (sequence <= after) { hitBoundary = true; break; }
+        if (sequence >= before) continue;
+        if (collected.length >= cap) break;
+        collected.push(event);
+        smallest = sequence;
+        if (largest === null) largest = sequence;
+      }
+    } finally { fs.closeSync(fd); }
+    const truncated = !hitBoundary;
+    return {
+      events: collected.reverse(),
+      complete: hitBoundary && !mixedEra,
+      truncated,
+      fromSequence: smallest,
+      toSequence: largest,
+      nextBeforeSequence: truncated && smallest !== null ? smallest : null,
+      highWater: this.highWater,
+      incomplete: this.incomplete,
+    };
+  }
+
+  // Exact lookup of one committed numbered row, scanned backwards with an
+  // early exit: rows arrive in ascending order, so the first row numbered
+  // below the target proves the target absent. Returns null when the row
+  // cannot be proven present.
+  durableRow(sequence) {
+    const target = Number(sequence);
+    if (!Number.isSafeInteger(target) || target <= 0 || !this.exists) return null;
+    const fd = fs.openSync(this.file, 'r');
+    try {
+      for (const line of reverseLines(fd, fs.fstatSync(fd).size)) {
+        const item = parseLine(line.text);
+        if (item.schema === HEADER) break;
+        if (item.type === 'workbench/history-checkpoint' || item.type === 'workbench/history-gap') continue;
+        const own = Number(item.sequence);
+        if (own === target) return item;
+        if (Number.isSafeInteger(own) && own < target) break;
+      }
+    } finally { fs.closeSync(fd); }
+    return null;
+  }
+
+  // The recovery gap is control metadata in the journal's own row space and
+  // earns the same receipt contract as durable facts: the marker counts as
+  // recorded only after a proven write+fsync, so a failed write keeps the
+  // original rows and a retryable state instead of silently skipping the
+  // marker on a later call. The interval is rewritten only when it changes.
+  recordRecoveryGap(from, to) {
+    const start = Number(from), end = Number(to);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start <= 0 || end < start) {
+      return { ok: false, phase: 'input', highWater: this.highWater };
+    }
+    this.recoveryGap = { from: start, to: end, sessionId: this.sessionId };
+    if (this.gapRecorded && this.gapRecorded.from === start && this.gapRecorded.to === end) {
+      return { ok: true, phase: 'already-recorded', highWater: this.highWater };
+    }
+    // The marker is control metadata, not a native fact: its failed receipt
+    // is diagnosed through the return value and onError, but it must not
+    // raise the sticky read veto - readers keep serving with the in-memory
+    // gap instead of losing the whole journal to a metadata write.
+    const priorError = this.error;
+    const receipt = this._commitDurableRows([{ type: 'workbench/history-gap', from: start, to: end, sessionId: this.sessionId }]);
+    if (!receipt.ok) this.error = priorError;
+    if (receipt.ok) {
+      this.gapRecorded = { from: start, to: end };
+      // A landed marker declares the hole honestly; rows above the interval
+      // may flush again. The retained failed batch (if any) stays retained:
+      // its sequences sit inside the interval and belong to a retry.
+      if (this.durableBarrier && this.durableBarrier.phase === 'gap-marker') this.durableBarrier = null;
+    } else if (!this.durableBarrier) {
+      // While the marker itself cannot be proven on disk, no plain row may
+      // flush past the unrecorded hole either.
+      this.durableBarrier = { sequence: start, phase: 'gap-marker' };
+    }
+    return { ...receipt, highWater: this.highWater };
+  }
+
+  containsNativeFacts() {
+    if (!this.exists) return false;
+    const fd = fs.openSync(this.file, 'r');
+    try {
+      for (const line of reverseLines(fd, fs.fstatSync(fd).size)) {
+        if (!line.text.includes('"claude/native-')) continue;
+        if (isNativeFactType(parseLine(line.text).type)) return true;
+      }
+    } finally { fs.closeSync(fd); }
+    return false;
+  }
+
+  seedRecovered(events, streamSequence) {
+    // A valid-but-incomplete archive that already carries native facts is
+    // collected evidence: replacing it with a recovered chat transcript
+    // would destroy task rows no other source can rebuild. Keep the file
+    // and the incomplete flag; the refusal is an explicit receipt.
+    if (this.exists && this.containsNativeFacts()) {
+      this.incomplete = true;
+      const refusal = Object.assign(new Error('会话历史含原生任务事实，拒绝恢复覆盖；原文件已保留。'), { code: 'HISTORY_NATIVE_FACTS_REFUSED' });
+      this.onError(refusal);
+      return { ok: false, refused: true, reason: 'native-facts', highWater: this.highWater };
+    }
+    const recovered = [];
+    for (const event of events) compactInto(recovered, { ...event, at: event.at || this.startedAt, sessionId: this.sessionId, contextId: this.contextId, sequence: 0 });
+    recovered.push({ type: 'workbench/history-checkpoint', streamSequence });
+    const header = { schema: HEADER, sessionId: this.sessionId, contextId: this.contextId, incomplete: false, fileId: crypto.randomUUID(), createdAt: new Date().toISOString() };
+    const temporary = `${this.file}.${process.pid}.${crypto.randomUUID()}.recovery.tmp`;
+    try {
+      fs.mkdirSync(path.dirname(this.file), { recursive: true });
+      fs.writeFileSync(temporary, [header, ...recovered].map(item => JSON.stringify(item)).join('\n') + '\n', { mode: 0o600, flag: 'wx' });
+      fs.renameSync(temporary, this.file);
+      this.pending = []; this.highWater = streamSequence; this.incomplete = false; this.exists = true; this.error = null;
+      this.fileId = header.fileId; this.createdAt = header.createdAt;
+      return { ok: true, refused: false, highWater: this.highWater };
+    } catch (error) {
+      this.onError(error);
+      return { ok: false, refused: false, error: error.message, code: error.code || null, highWater: this.highWater };
+    } finally { try { fs.unlinkSync(temporary); } catch {} }
+  }
+
+  // Forward-only: a checkpoint may raise the mark (numbers the counter
+  // consumed without journaling rows) but may never lower it — old rows
+  // keep their numbering and nothing re-mints a sequence the archive
+  // already holds. A frozen journal refuses: the mark must not jump a
+  // failed head, and the checkpoint row would flush above the barrier.
+  resetStreamSequence(streamSequence) {
+    const target = Number(streamSequence);
+    if (!Number.isSafeInteger(target) || target <= this.highWater) return false;
+    if (this.durableBarrier) return false;
+    this.highWater = target;
+    this.pending.push({ type: 'workbench/history-checkpoint', streamSequence: target });
+    this.flush();
+    return true;
+  }
+
+  // Land queued plain rows. Without a ceiling the call is a free flush: it
+  // is refused while a durable barrier is armed (rows above a failed head
+  // must never reach the file first) and re-arms the timer so an unfrozen
+  // journal drains later. A ceiling (the staged head of a durable commit)
+  // lands only the rows that sit below it, keeping arrival order even
+  // during a retry of the retained failed batch. Rows queued while frozen
+  // never raised the in-memory mark, so a successful flush adopts the
+  // highest written sequence instead.
+  flush(ceiling) {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    const limit = Number.isSafeInteger(ceiling) && ceiling > 0 ? ceiling : null;
+    if (this.durableBarrier && limit === null) {
+      if (this.pending.length && !this.timer) {
+        this.timer = setTimeout(() => { this.timer = null; this.flush(); }, 250);
+        this.timer.unref?.();
+      }
+      return;
+    }
+    if (!this.pending.length) return;
+    let rows = this.pending;
+    if (limit !== null) {
+      let split = rows.length;
+      for (let i = 0; i < rows.length; i++) {
+        const own = Number(rows[i].streamSequence ?? rows[i].sequence);
+        if (Number.isSafeInteger(own) && own >= limit) { split = i; break; }
+      }
+      if (split === 0) return;
+      rows = rows.slice(0, split);
+    }
+    let fd, start;
+    try {
+      fs.mkdirSync(path.dirname(this.file), { recursive: true });
+      if (!this.exists) {
+        const header = this._newHeader();
+        fs.writeFileSync(this.file, `${JSON.stringify(header)}\n`, { flag: 'wx', mode: 0o600 });
+        this.exists = true;
+        this.fileId = header.fileId;
+        this.createdAt = header.createdAt;
+      }
+      const payload = Buffer.from(rows.map(event => JSON.stringify(event)).join('\n') + '\n');
+      fd = fs.openSync(this.file, 'r+', 0o600);
+      start = fs.fstatSync(fd).size;
+      let written = 0;
+      while (written < payload.length) {
+        const count = fs.writeSync(fd, payload, written, payload.length - written, start + written);
+        if (!count) throw Object.assign(new Error('history write made no progress'), { code: 'EIO' });
+        written += count;
+      }
+      this.pending = this.pending.slice(rows.length);
+      let landed = 0;
+      for (const row of rows) {
+        const own = Number(row.streamSequence ?? row.sequence);
+        if (Number.isSafeInteger(own) && own > landed) landed = own;
+      }
+      if (landed > this.highWater) this.highWater = landed;
+      this.error = null;
+    } catch (error) {
+      // A failed append must not leave half a JSON line before the retry.
+      // This archive has one owning service/writer; prior complete rows stay intact.
+      if (fd !== undefined && start !== undefined) try { fs.ftruncateSync(fd, start); } catch {}
+      this.error = error.code || 'HISTORY_WRITE_FAILED';
+      this.onError(error);
+    } finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+
+  read({ before, limit = 20 } = {}) {
+    const count = Number(limit);
+    if (!Number.isInteger(count) || count < 1 || count > 100) throw Object.assign(new Error('limit must be between 1 and 100'), { status: 400 });
+    if (before !== undefined && before !== null && !/^[1-9]\d*$/.test(String(before))) throw Object.assign(new Error('invalid history cursor'), { status: 400 });
+    this.flush();
+    if (this.error) throw Object.assign(new Error('会话历史写入失败，请检查磁盘与本地日志。'), { status: 503, code: this.error });
+    if (!this.exists) return { events: [], nextCursor: null, incomplete: this.incomplete, highWater: this.highWater, ...(this.recoveryGap ? { recoveryGap: this.recoveryGap } : {}) };
+    const fd = fs.openSync(this.file, 'r');
+    const selected = [], prelude = [];
+    let cursor = null, prompts = 0;
+    try {
+      const size = fs.fstatSync(fd).size;
+      const end = before == null ? size : Number(before);
+      if (!Number.isSafeInteger(end) || end > size) throw Object.assign(new Error('invalid history cursor'), { status: 400 });
+      if (before != null) {
+        const previous = Buffer.alloc(1); fs.readSync(fd, previous, 0, 1, end - 1);
+        if (previous[0] !== 10) throw Object.assign(new Error('invalid history cursor'), { status: 400 });
+      }
+      let boundary = null;
+      for (const line of reverseLines(fd, end)) {
+        const event = parseLine(line.text);
+        if (event.schema === HEADER || event.type === 'workbench/history-checkpoint' || event.type === 'workbench/history-gap') continue;
+        if (prompts >= count) {
+          if (event.type === 'claude/user-prompt') { cursor = boundary; break; }
+          prelude.push(event);
+          continue;
+        }
+        selected.push(event);
+        if (event.type === 'claude/user-prompt') { prompts++; boundary = line.offset; }
+      }
+      if (cursor === null) selected.push(...prelude);
+    } finally { fs.closeSync(fd); }
+    const events = [];
+    for (const event of selected.reverse()) compactInto(events, event);
+    return { events, nextCursor: cursor === null ? null : String(cursor), incomplete: this.incomplete, highWater: this.highWater, ...(this.recoveryGap ? { recoveryGap: this.recoveryGap } : {}) };
+  }
+
+  // Shutdown contract for a journaled history: a retained failed batch is
+  // retried in place first; only if that still fails is the hole persisted
+  // as a recovery-gap marker (never the other way around - the queue is
+  // never cleared to fake a drain). A landed marker lets the frozen plain
+  // rows flush as an honest partial refill; a marker that cannot land
+  // leaves everything queued and the failure diagnosable.
+  close() {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    if (this.failedBatch) {
+      const retried = this.retryFailedBatch();
+      if (!retried.ok) {
+        const head = this.failedBatch[0].sequence;
+        let ceiling = this.failedBatch[this.failedBatch.length - 1].sequence;
+        for (const row of this.pending) {
+          const own = Number(row.streamSequence ?? row.sequence);
+          if (Number.isSafeInteger(own) && own > ceiling) ceiling = own;
+        }
+        this.recordRecoveryGap(head, ceiling);
+      }
+    }
+    this.flush();
+  }
+}
+
+module.exports = { SessionHistory, compactInto, reverseLines };