@adhdev/daemon-core 0.9.82-rc.47 → 0.9.82-rc.470

package/src/config/chat-history.ts

@@ -58,6 +58,40 @@ const savedHistoryFileSummaryCache = new Map<string, SavedHistoryFileSummaryCach
 const savedHistoryBackgroundRefresh = new Set<string>();
 const savedHistoryRollupInFlight = new Set<string>();
 
+// Bounded-tail read cache. The dashboard re-subscribes and polls hot sessions
+// every ~2.5s; without a cache each poll re-reads/parses/sorts the whole
+// conversation just to slice a small tail. We key on (type, sessionId,
+// pagination args) plus the on-disk size+mtime signature so an UNCHANGED
+// session returns the previously computed tail in O(1) and only re-reads when a
+// new message is appended (signature changes). The map is bounded by a small
+// LRU to keep memory flat regardless of how many sessions are touched.
+interface BoundedTailCacheEntry {
+    signature: string;
+    result: { messages: HistoryMessage[]; hasMore: boolean };
+}
+
+const BOUNDED_TAIL_CACHE_MAX_ENTRIES = 64;
+const boundedTailReadCache = new Map<string, BoundedTailCacheEntry>();
+
+function readBoundedTailCache(key: string, signature: string): { messages: HistoryMessage[]; hasMore: boolean } | null {
+    const cached = boundedTailReadCache.get(key);
+    if (!cached || cached.signature !== signature) return null;
+    // Refresh LRU recency.
+    boundedTailReadCache.delete(key);
+    boundedTailReadCache.set(key, cached);
+    return cached.result;
+}
+
+function writeBoundedTailCache(key: string, signature: string, result: { messages: HistoryMessage[]; hasMore: boolean }): void {
+    boundedTailReadCache.delete(key);
+    boundedTailReadCache.set(key, { signature, result });
+    while (boundedTailReadCache.size > BOUNDED_TAIL_CACHE_MAX_ENTRIES) {
+        const oldest = boundedTailReadCache.keys().next().value;
+        if (oldest === undefined) break;
+        boundedTailReadCache.delete(oldest);
+    }
+}
+
 interface HistoryMessage {
     ts: string;           // ISO timestamp
     receivedAt: number;   // epoch ms
@@ -138,6 +172,15 @@ function collapseReplayAssistantTurns(messages: HistoryMessage[], historyBehavio
         }
 
         if (message.role === 'assistant') {
+            // Tool / activity bubbles are distinct events, not replayed prose —
+            // collapsing them would erase every tool call and result after the
+            // turn's first assistant message. Only consecutive *prose* assistant
+            // turns are the replay-dedup target this collapse exists for.
+            const isActivity = message.kind === 'tool' || message.kind === 'terminal' || message.kind === 'thought';
+            if (isActivity) {
+                collapsed.push(message);
+                continue;
+            }
             if (sawAssistantSinceLastUser) continue;
             sawAssistantSinceLastUser = true;
             collapsed.push(message);
@@ -1180,6 +1223,324 @@ function pageHistoryRecords(
     return { messages: sliced, hasMore: startInclusive > 0 };
 }
 
+// A finite tail request can be served by reading only the newest files instead
+// of the whole conversation. Treat very large limits (e.g. MAX_SAFE_INTEGER, or
+// anything past a generous ceiling) as a full-history request so restore/seed
+// callers keep their existing behavior.
+const BOUNDED_TAIL_MAX_LIMIT = 5_000;
+// Slack added to the requested window before sorting/dedup/collapse so the
+// boundary message at the top of the tail dedupes/collapses identically to a
+// full read. Modest and bounded — it only widens the parse window, not output.
+const BOUNDED_TAIL_SLACK = 50;
+
+function isBoundedTailRequest(limit: number, offset: number, excludeRecentCount: number): boolean {
+    const numericLimit = Number(limit);
+    if (!Number.isFinite(numericLimit) || numericLimit <= 0) return false;
+    if (numericLimit > BOUNDED_TAIL_MAX_LIMIT) return false;
+    const numericOffset = Number(offset);
+    const numericExclude = Number(excludeRecentCount);
+    if (!Number.isFinite(numericOffset) || !Number.isFinite(numericExclude)) return false;
+    return true;
+}
+
+// Byte threshold below which a file is small enough that reading the whole
+// thing is cheaper than seeking. Reverse-seek pays off only on large files.
+const REVERSE_TAIL_SMALL_FILE_BYTES = 64 * 1024;
+// Chunk size for backward reads. We read the file tail one chunk at a time
+// (newest bytes first) until we have collected enough complete lines.
+const REVERSE_TAIL_CHUNK_BYTES = 64 * 1024;
+
+// Per-(file path) incremental tail cache. A hot session's daily JSONL file grows
+// append-only while it generates; the size+mtime signature on the bounded-tail
+// read cache therefore invalidates on every append and forces a full re-read.
+// Here we keep the most recently decoded tail LINES for a file plus the byte
+// length we read them from. When the file has only grown (append-only: size
+// increased, the previously-read prefix is unchanged) we read just the new bytes
+// from `size` onward and splice them onto the retained tail — no full re-parse.
+// Truncation/rotation (size shrank, or a fresh inode) drops the entry and falls
+// back to a full reverse-seek.
+interface IncrementalTailCacheEntry {
+    // File length (bytes) we have already consumed into `lines`.
+    size: number;
+    mtimeMs: number;
+    // Decoded complete lines (oldest-first) covering at least the tail window.
+    // Bounded to TAIL_LINES_RETAINED so memory stays flat for huge files.
+    lines: string[];
+    // True when `lines` is the entire file (head reached), so older pages can
+    // trust that nothing precedes the retained window.
+    coversWholeFile: boolean;
+}
+
+// How many trailing lines we retain per file. The bounded-tail caller never
+// asks for more than BOUNDED_TAIL_MAX_LIMIT + slack; keep a generous multiple so
+// repeated reads at the same window are served incrementally.
+const TAIL_LINES_RETAINED = BOUNDED_TAIL_MAX_LIMIT + 2 * BOUNDED_TAIL_SLACK;
+const INCREMENTAL_TAIL_CACHE_MAX_ENTRIES = 64;
+const incrementalTailCache = new Map<string, IncrementalTailCacheEntry>();
+
+function evictIncrementalTailCache(): void {
+    while (incrementalTailCache.size > INCREMENTAL_TAIL_CACHE_MAX_ENTRIES) {
+        const oldest = incrementalTailCache.keys().next().value;
+        if (oldest === undefined) break;
+        incrementalTailCache.delete(oldest);
+    }
+}
+
+// Split a Buffer into complete lines plus a leftover head fragment, partitioning
+// only on the newline byte (0x0A). 0x0A never appears inside a multibyte UTF-8
+// sequence, so decoding each complete byte segment is boundary-safe. The leftover
+// (bytes before the first newline) is returned undecoded so a caller stitching
+// chunks together never splits a multibyte char.
+function splitBufferLines(buf: Buffer): { head: Buffer; lines: string[] } {
+    const lines: string[] = [];
+    let lineEnd = buf.length;
+    let firstNewline = -1;
+    for (let i = buf.length - 1; i >= 0; i--) {
+        if (buf[i] !== 0x0a) continue;
+        if (i + 1 < lineEnd) {
+            lines.push(buf.toString('utf-8', i + 1, lineEnd));
+        }
+        lineEnd = i;
+        firstNewline = i;
+    }
+    // Lines were collected newest-first; restore oldest-first for the segment
+    // that follows the first (lowest-index) newline.
+    lines.reverse();
+    const head = firstNewline >= 0 ? buf.subarray(0, firstNewline) : buf;
+    return { head, lines };
+}
+
+// Read the last bytes of a file, newest-first, until we have at least `needed`
+// complete lines (or reach the start of the file). Returns lines oldest-first and
+// whether the whole file was consumed. Boundary-safe: lines are cut on the
+// newline byte only, so multibyte UTF-8 chars are never split, and a trailing
+// partial line (no terminating newline) is preserved as a complete final line.
+function readReverseTailLines(filePath: string, needed: number): { lines: string[]; coversWholeFile: boolean; size: number; mtimeMs: number } {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const stat = fs.fstatSync(fd);
+        const size = stat.size;
+        let position = size;
+        // `carry` holds bytes belonging to a line that straddles the current
+        // chunk boundary (its start is in an older, not-yet-read chunk).
+        let carry: Buffer = Buffer.alloc(0);
+        const collected: string[] = [];
+
+        while (position > 0 && collected.length < needed) {
+            const chunkSize = Math.min(REVERSE_TAIL_CHUNK_BYTES, position);
+            position -= chunkSize;
+            const chunk = Buffer.alloc(chunkSize);
+            fs.readSync(fd, chunk, 0, chunkSize, position);
+            const combined = carry.length ? Buffer.concat([chunk, carry]) : chunk;
+            const { head, lines } = splitBufferLines(combined);
+            // `head` is the (possibly partial) line whose start lies further back;
+            // hold it for the next (older) chunk to complete.
+            carry = head;
+            // `lines` are oldest-first within this combined buffer; prepend them
+            // ahead of what we already collected (which is strictly newer).
+            for (let i = lines.length - 1; i >= 0; i--) {
+                collected.push(lines[i]);
+            }
+        }
+
+        const reachedStart = position <= 0;
+        if (reachedStart && carry.length) {
+            // Leftover head at the start of the file is itself a complete line.
+            collected.push(carry.toString('utf-8'));
+        }
+        // `collected` is newest-first; restore oldest-first.
+        collected.reverse();
+        return { lines: collected, coversWholeFile: reachedStart, size, mtimeMs: stat.mtimeMs };
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+// Return the tail lines (oldest-first) for a single history file, reading as
+// little of the file as possible. Strategy:
+//   - Small files: one readFileSync (seeking is not worth the syscalls).
+//   - Large files: reverse byte-seek for the newest `needed` lines.
+//   - Append-only growth since the last read: read only the appended bytes and
+//     splice them onto the retained tail (no full re-parse) — this is what keeps
+//     a hot, still-generating session cheap to poll.
+// `needed` is a soft floor; we may return more (whole small files / retained
+// window). Lines include any trailing partial (unterminated) final line.
+function readFileTailLines(filePath: string, needed: number): { lines: string[]; coversWholeFile: boolean } {
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(filePath);
+    } catch {
+        return { lines: [], coversWholeFile: true };
+    }
+    const size = stat.size;
+    const mtimeMs = stat.mtimeMs;
+    if (size === 0) {
+        incrementalTailCache.delete(filePath);
+        return { lines: [], coversWholeFile: true };
+    }
+
+    const cached = incrementalTailCache.get(filePath);
+    if (cached) {
+        if (cached.size === size && cached.mtimeMs === mtimeMs) {
+            // Unchanged since last read — reuse retained tail. Refresh LRU.
+            incrementalTailCache.delete(filePath);
+            incrementalTailCache.set(filePath, cached);
+            if (cached.coversWholeFile || cached.lines.length >= needed) {
+                return { lines: cached.lines, coversWholeFile: cached.coversWholeFile };
+            }
+            // Retained window is smaller than this request needs; fall through
+            // to a fresh reverse-seek for the larger window.
+        } else if (size > cached.size) {
+            // Append-only growth: the prefix [0, cached.size) is assumed
+            // unchanged (JSONL is append-only). Read just the new bytes and
+            // stitch them — but verify the byte at cached.size-1 is still the
+            // newline that terminated our last retained line, so a rewrite that
+            // happens to grow the file (compaction) is detected and rejected.
+            const incremental = tryIncrementalTailGrowth(filePath, cached, size, mtimeMs, needed);
+            if (incremental) return { lines: incremental.lines, coversWholeFile: incremental.coversWholeFile };
+        }
+        // size shrank (truncation/rotation) or incremental failed → drop & reload.
+        incrementalTailCache.delete(filePath);
+    }
+
+    if (size <= REVERSE_TAIL_SMALL_FILE_BYTES) {
+        let content: string;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        } catch {
+            return { lines: [], coversWholeFile: true };
+        }
+        const lines = content.split('\n');
+        // A trailing newline yields a final empty element; drop only that one so
+        // an unterminated partial last line is still preserved.
+        if (lines.length && lines[lines.length - 1] === '') lines.pop();
+        storeIncrementalTailCache(filePath, size, mtimeMs, lines, true);
+        return { lines, coversWholeFile: true };
+    }
+
+    let result: { lines: string[]; coversWholeFile: boolean; size: number; mtimeMs: number };
+    try {
+        result = readReverseTailLines(filePath, needed);
+    } catch {
+        return { lines: [], coversWholeFile: true };
+    }
+    storeIncrementalTailCache(filePath, result.size, result.mtimeMs, result.lines, result.coversWholeFile);
+    return { lines: result.lines, coversWholeFile: result.coversWholeFile };
+}
+
+// Read appended bytes [cached.size, size) and splice them onto the retained tail.
+// Returns null if the prior byte is not a newline (the retained tail did not end
+// on a record boundary, e.g. the file was rewritten) so the caller can full-reload.
+function tryIncrementalTailGrowth(
+    filePath: string,
+    cached: IncrementalTailCacheEntry,
+    size: number,
+    mtimeMs: number,
+    needed: number,
+): { lines: string[]; coversWholeFile: boolean } | null {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        // Confirm the byte ending the previously-read prefix is still a newline.
+        if (cached.size > 0) {
+            const boundary = Buffer.alloc(1);
+            fs.readSync(fd, boundary, 0, 1, cached.size - 1);
+            if (boundary[0] !== 0x0a) return null;
+        }
+        const appendedLength = size - cached.size;
+        const appended = Buffer.alloc(appendedLength);
+        fs.readSync(fd, appended, 0, appendedLength, cached.size);
+        const newLines = appended.toString('utf-8').split('\n');
+        if (newLines.length && newLines[newLines.length - 1] === '') newLines.pop();
+        const merged = cached.lines.concat(newLines);
+        // Keep memory flat: retain only the trailing window.
+        const trimmed = merged.length > TAIL_LINES_RETAINED
+            ? merged.slice(merged.length - TAIL_LINES_RETAINED)
+            : merged;
+        const coversWholeFile = cached.coversWholeFile && trimmed.length === merged.length;
+        storeIncrementalTailCache(filePath, size, mtimeMs, trimmed, coversWholeFile);
+        if (coversWholeFile || trimmed.length >= needed) {
+            return { lines: trimmed, coversWholeFile };
+        }
+        // Should not happen (we only grew), but be safe.
+        return { lines: trimmed, coversWholeFile };
+    } catch {
+        return null;
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+function storeIncrementalTailCache(filePath: string, size: number, mtimeMs: number, lines: string[], coversWholeFile: boolean): void {
+    const retained = lines.length > TAIL_LINES_RETAINED ? lines.slice(lines.length - TAIL_LINES_RETAINED) : lines;
+    const covers = coversWholeFile && retained.length === lines.length;
+    incrementalTailCache.delete(filePath);
+    incrementalTailCache.set(filePath, { size, mtimeMs, lines: retained, coversWholeFile: covers });
+    evictIncrementalTailCache();
+}
+
+// Read newest-first only as many files as needed to cover the requested window
+// plus slack. listHistoryFiles already returns files reversed (newest-first), so
+// we accumulate (de-duped) candidates from the end and stop once we have enough,
+// then hand the bounded window to pageHistoryRecords in chronological order.
+function readBoundedTailRecords(
+    agentType: string,
+    dir: string,
+    files: string[],
+    needed: number,
+): { records: HistoryMessage[]; readAllFiles: boolean } {
+    const collected: HistoryMessage[] = [];
+    const seen = new Set<string>();
+    let readAllFiles = true;
+
+    for (let f = 0; f < files.length; f++) {
+        const filePath = path.join(dir, files[f]);
+        // Read only the file tail needed to top up the window — for a large
+        // single-day file this seeks the last `needed` lines instead of parsing
+        // the whole file. We re-derive the per-file floor each iteration from how
+        // many records are still missing (plus slack so dedup at the boundary is
+        // stable), capped at `needed`.
+        const remaining = Math.max(0, needed - collected.length);
+        const perFileNeeded = Math.min(needed, remaining + BOUNDED_TAIL_SLACK);
+        const { lines, coversWholeFile } = readFileTailLines(filePath, perFileNeeded);
+        // Walk this file's tail lines newest-first so we fill the tail window from
+        // the bottom. seen-dedup keeps the same first-wins-by-newest semantics the
+        // full read produced (files are processed newest-first there too).
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (!line) continue;
+            try {
+                const parsed = JSON.parse(line) as HistoryMessage;
+                const sanitizedMessage = sanitizeHistoryMessage(agentType, parsed);
+                if (!sanitizedMessage) continue;
+                const hash = buildHistoryMessageHash(agentType, sanitizedMessage);
+                if (seen.has(hash)) continue;
+                seen.add(hash);
+                collected.push(sanitizedMessage);
+            } catch { /* skip invalid lines */ }
+        }
+        // If we only read this file's tail (its head was not reached), older
+        // messages remain within this very file — the conversation is NOT fully
+        // represented even if this is the last file, so hasMore must stay true.
+        if (!coversWholeFile) {
+            readAllFiles = false;
+            break;
+        }
+        // Stop once we have the window AND there is at least one more file (so a
+        // potential older boundary message exists). If this is the last file we
+        // fall through and mark the whole history as read.
+        if (collected.length >= needed && f < files.length - 1) {
+            readAllFiles = false;
+            break;
+        }
+    }
+
+    // collected is newest-first across the bounded window; restore chronological
+    // (oldest-first) order before paging. pageHistoryRecords re-sorts by
+    // receivedAt regardless, so this is purely for stable input ordering.
+    collected.reverse();
+    return { records: collected, readAllFiles };
+}
+
 export function readChatHistory(
     agentType: string,
     offset: number = 0,
@@ -1196,6 +1557,33 @@ export function readChatHistory(
  // JSONL file list — filter by persistent history key when specified
         const files = listHistoryFiles(dir, historySessionId);
 
+        const bounded = isBoundedTailRequest(limit, offset, excludeRecentCount);
+
+        if (bounded) {
+            const fileSignatures = buildSavedHistoryFileSignatureMap(dir, files);
+            const cacheKey = `${sanitized}\0${historySessionId || ''}\0${offset}\0${limit}\0${excludeRecentCount}\0${historyBehavior?.collapseConsecutiveAssistantTurns ? '1' : '0'}`;
+            const signature = buildSavedHistoryCacheSignature(files, fileSignatures);
+            const cached = readBoundedTailCache(cacheKey, signature);
+            if (cached) return cached;
+
+            // Window large enough that the top boundary dedupes/collapses the same
+            // as a full read. hasMore reflects whether older messages exist beyond
+            // the window we actually read.
+            const numericLimit = Math.max(1, Number(limit));
+            const numericOffset = Math.max(0, Number(offset));
+            const numericExclude = Math.max(0, Number(excludeRecentCount));
+            const needed = numericLimit + numericOffset + numericExclude + Math.max(BOUNDED_TAIL_SLACK, numericLimit);
+            const { records, readAllFiles } = readBoundedTailRecords(agentType, dir, files, needed);
+            const result = pageHistoryRecords(agentType, records, offset, limit, excludeRecentCount, historyBehavior);
+            // If we read every file, the conversation is fully represented in the
+            // window and pageHistoryRecords' hasMore is authoritative. If we
+            // stopped early there are older messages we never read, so hasMore
+            // must stay true regardless of the in-window slice position.
+            const boundedResult = readAllFiles ? result : { messages: result.messages, hasMore: true };
+            writeBoundedTailCache(cacheKey, signature, boundedResult);
+            return boundedResult;
+        }
+
         const allMessages: HistoryMessage[] = [];
         const seen = new Set<string>();
 
@@ -1345,7 +1733,16 @@ function rewriteCanonicalSavedHistory(agentType: string, historySessionId: strin
 
 export type ProviderNativeHistoryScripts = Record<string, ((input: any) => any) | undefined>;
 
-type ProviderNativeHistoryReadResult = { records: HistoryMessage[]; sourcePath: string; sourceMtimeMs: number };
+type ProviderNativeHistoryReadResult = {
+    records: HistoryMessage[];
+    sourcePath: string;
+    sourceMtimeMs: number;
+    providerSessionId?: string;
+    workspace?: string;
+    nativeHistoryCoverage?: string;
+    partialReason?: string;
+    unavailableReason?: string;
+};
 
 function getNativeHistoryScriptName(canonicalHistory: ProviderCanonicalHistoryConfig | undefined, key: 'readSession' | 'listSessions'): string {
     const configured = canonicalHistory?.scripts?.[key];
@@ -1367,19 +1764,42 @@ function normalizeProviderNativeHistoryRecords(agentType: string, historySession
     if (!Array.isArray(records)) return [];
     const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId);
     return records
-        .map((record: any) => sanitizeHistoryMessage(agentType, {
-            ts: typeof record?.ts === 'string' ? record.ts : new Date(Number(record?.receivedAt) || Date.now()).toISOString(),
-            receivedAt: Number(record?.receivedAt) || Date.parse(record?.ts || '') || Date.now(),
-            role: record?.role,
-            content: String(record?.content || ''),
-            kind: record?.kind || (record?.role === 'system' ? 'session_start' : 'standard'),
-            senderName: record?.senderName,
-            agent: agentType,
-            instanceId: record?.instanceId,
-            historySessionId: normalizeSavedHistorySessionId(record?.historySessionId || normalizedSessionId),
-            sessionTitle: record?.sessionTitle,
-            workspace: record?.workspace,
-        } as HistoryMessage))
+        .map((record: any) => {
+            const base: HistoryMessage = {
+                ts: typeof record?.ts === 'string' ? record.ts : new Date(Number(record?.receivedAt) || Date.now()).toISOString(),
+                receivedAt: Number(record?.receivedAt) || Date.parse(record?.ts || '') || Date.now(),
+                role: record?.role,
+                content: String(record?.content || ''),
+                kind: record?.kind || (record?.role === 'system' ? 'session_start' : 'standard'),
+                senderName: record?.senderName,
+                agent: agentType,
+                instanceId: record?.instanceId,
+                historySessionId: normalizeSavedHistorySessionId(record?.historySessionId || normalizedSessionId),
+                sessionTitle: record?.sessionTitle,
+                workspace: record?.workspace,
+            } as HistoryMessage;
+            // (A2.3 v2 identity passthrough) — if the producer (native_history.js)
+            // emitted v2 stable identity, keep it across the sanitize layer so
+            // downstream (chat-commands.ts normalizeNativeHistoryMessages) sees
+            // the producer's contract output instead of recomputing from index
+            // and content hash. v1 producers without these fields are unaffected.
+            if (typeof record?.providerUnitKey === 'string' && record.providerUnitKey) {
+                (base as any).providerUnitKey = record.providerUnitKey;
+            }
+            if (typeof record?.bubbleId === 'string' && record.bubbleId) {
+                (base as any).bubbleId = record.bubbleId;
+            }
+            if (typeof record?.sequence === 'number' && Number.isFinite(record.sequence)) {
+                (base as any).sequence = record.sequence;
+            }
+            if (typeof record?._turnKey === 'string' && record._turnKey) {
+                (base as any)._turnKey = record._turnKey;
+            }
+            if (typeof record?.bubbleState === 'string' && record.bubbleState) {
+                (base as any).bubbleState = record.bubbleState;
+            }
+            return sanitizeHistoryMessage(agentType, base);
+        })
         .filter(Boolean) as HistoryMessage[];
 }
 
@@ -1387,27 +1807,51 @@ function callProviderNativeHistoryRead(
     agentType: string,
     canonicalHistory: ProviderCanonicalHistoryConfig | undefined,
     scripts: ProviderNativeHistoryScripts | undefined,
-    historySessionId: string,
+    historySessionId: string | undefined,
     workspace?: string,
+    excludeInProgressTurn?: boolean,
+    sessionStartedAtMs?: number,
+    envOverrides?: Record<string, string>,
+    forceRefresh?: boolean,
 ): ProviderNativeHistoryReadResult | null {
     const fn = getProviderNativeHistoryScript(scripts, canonicalHistory, 'readSession');
     if (!fn) return null;
+    const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId || '');
     const result = fn({
         agentType,
-        sessionId: historySessionId,
-        historySessionId,
+        sessionId: normalizedSessionId,
+        // Arm the native-history executor's session pin guard. When the
+        // instance is already bound to a provider session, pass that id as
+        // `providerSessionId` so the executor rejects any *other* newest
+        // session it would otherwise pick (hermes ≥0.14 creates a fresh
+        // `sessions` row per internal sub-session, so an unpinned
+        // newest-wins query drifts to a different id on every read →
+        // re-bind churn + unbounded history re-hydration). When there is no
+        // bound id yet (first-bind / workspace-only discovery) this is '',
+        // which leaves the guard disarmed so discovery still works.
+        providerSessionId: normalizedSessionId,
+        historySessionId: normalizedSessionId,
         workspace,
         format: canonicalHistory?.format,
         watchPath: canonicalHistory?.watchPath,
-        args: { sessionId: historySessionId, historySessionId, workspace },
+        excludeInProgressTurn: excludeInProgressTurn === true,
+        sessionStartedAtMs,
+        envOverrides,
+        forceRefresh: forceRefresh === true,
+        args: { sessionId: normalizedSessionId, historySessionId: normalizedSessionId, workspace, excludeInProgressTurn: excludeInProgressTurn === true, sessionStartedAtMs, envOverrides, forceRefresh: forceRefresh === true },
     });
     if (!result || typeof result !== 'object') return null;
-    const records = normalizeProviderNativeHistoryRecords(agentType, historySessionId, (result as any).messages || (result as any).records);
+    const records = normalizeProviderNativeHistoryRecords(agentType, normalizedSessionId, (result as any).messages || (result as any).records);
     if (records.length === 0) return null;
     return {
         records,
         sourcePath: typeof (result as any).sourcePath === 'string' ? (result as any).sourcePath : '',
         sourceMtimeMs: Number((result as any).sourceMtimeMs) || 0,
+        providerSessionId: typeof (result as any).providerSessionId === 'string' ? (result as any).providerSessionId.trim() : undefined,
+        workspace: typeof (result as any).workspace === 'string' ? (result as any).workspace.trim() : undefined,
+        nativeHistoryCoverage: typeof (result as any).nativeHistoryCoverage === 'string' ? (result as any).nativeHistoryCoverage.trim() : undefined,
+        partialReason: typeof (result as any).partialReason === 'string' ? (result as any).partialReason.trim() : undefined,
+        unavailableReason: typeof (result as any).unavailableReason === 'string' ? (result as any).unavailableReason.trim() : undefined,
     };
 }
 
@@ -1417,10 +1861,15 @@ function buildNativeHistoryReadResult(
     scripts: ProviderNativeHistoryScripts | undefined,
     historySessionId: string | undefined,
     workspace?: string,
+    excludeInProgressTurn?: boolean,
+    sessionStartedAtMs?: number,
+    envOverrides?: Record<string, string>,
+    forceRefresh?: boolean,
 ): ProviderNativeHistoryReadResult | null {
     const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId || '');
-    if (!canonicalHistory || !normalizedSessionId || !isNativeSourceCanonicalHistory(canonicalHistory)) return null;
-    return callProviderNativeHistoryRead(agentType, canonicalHistory, scripts, normalizedSessionId, workspace);
+    const normalizedWorkspace = typeof workspace === 'string' ? workspace.trim() : '';
+    if (!canonicalHistory || (!normalizedSessionId && !normalizedWorkspace) || !isNativeSourceCanonicalHistory(canonicalHistory)) return null;
+    return callProviderNativeHistoryRead(agentType, canonicalHistory, scripts, normalizedSessionId, workspace, excludeInProgressTurn, sessionStartedAtMs, envOverrides, forceRefresh);
 }
 
 function materializeNativeHistoryToMirror(
@@ -1476,16 +1925,36 @@ export function readProviderChatHistory(
         excludeRecentCount?: number;
         historyBehavior?: ProviderHistoryBehavior;
         scripts?: ProviderNativeHistoryScripts;
+        excludeInProgressTurn?: boolean;
+        sessionStartedAtMs?: number;
+        envOverrides?: Record<string, string>;
+        forceRefresh?: boolean;
     } = {},
-): { messages: HistoryMessage[]; hasMore: boolean; source: 'provider-native' | 'adhdev-mirror' | 'native-unavailable'; sourcePath?: string; sourceMtimeMs?: number } {
-    if (isNativeSourceCanonicalHistory(options.canonicalHistory) && options.historySessionId) {
-        const nativeResult = buildNativeHistoryReadResult(agentType, options.canonicalHistory, options.scripts, options.historySessionId, options.workspace);
+): {
+    messages: HistoryMessage[];
+    hasMore: boolean;
+    source: 'provider-native' | 'adhdev-mirror' | 'native-unavailable';
+    sourcePath?: string;
+    sourceMtimeMs?: number;
+    providerSessionId?: string;
+    workspace?: string;
+    nativeHistoryCoverage?: string;
+    partialReason?: string;
+    unavailableReason?: string;
+} {
+    if (isNativeSourceCanonicalHistory(options.canonicalHistory) && (options.historySessionId || options.workspace)) {
+        const nativeResult = buildNativeHistoryReadResult(agentType, options.canonicalHistory, options.scripts, options.historySessionId, options.workspace, options.excludeInProgressTurn, options.sessionStartedAtMs, options.envOverrides, options.forceRefresh);
         if (!nativeResult) return { messages: [], hasMore: false, source: 'native-unavailable' };
         return {
             ...pageHistoryRecords(agentType, nativeResult.records, options.offset || 0, options.limit || 30, options.excludeRecentCount || 0, options.historyBehavior),
             source: 'provider-native',
             sourcePath: nativeResult.sourcePath,
             sourceMtimeMs: nativeResult.sourceMtimeMs,
+            providerSessionId: nativeResult.providerSessionId,
+            workspace: nativeResult.workspace,
+            nativeHistoryCoverage: nativeResult.nativeHistoryCoverage,
+            partialReason: nativeResult.partialReason,
+            unavailableReason: nativeResult.unavailableReason,
         };
     }
     return {

package/src/config/config.ts

@@ -123,6 +123,22 @@ export interface ADHDevConfig {
  // Optional explicit provider override root (for example a local adhdev-providers checkout)
     providerDir?: string;
 
+    /**
+     * Optional provider registry base URL override (for example a self-hosted
+     * registry). Highest-priority source in the registry resolver, ahead of the
+     * `ADHDEV_REGISTRY_URL` env var and the vendor default. See
+     * `config/registry-resolver.ts`.
+     */
+    registryUrl?: string;
+
+    /**
+     * Optional provider tarball (archive) URL override so self-hosters can point
+     * the daemon at their own provider mirror instead of the vendor GitHub repo.
+     * Highest-priority source, ahead of `ADHDEV_PROVIDER_TARBALL_URL` and the
+     * vendor default. See `config/registry-resolver.ts`.
+     */
+    providerTarballUrl?: string;
+
     /** Preferred daemon update channel. Defaults to stable/latest. */
     updateChannel?: ReleaseChannel;
 
@@ -233,6 +249,8 @@ function normalizeConfig(raw: unknown): ADHDevConfig & { activeWorkspaceId?: str
         ideSettings: isPlainObject(parsed.ideSettings) ? parsed.ideSettings : {},
         providerSourceMode: resolveProviderSourceMode(parsed.providerSourceMode, parsed.disableUpstream),
         providerDir: asOptionalString(parsed.providerDir),
+        registryUrl: asOptionalString(parsed.registryUrl),
+        providerTarballUrl: asOptionalString(parsed.providerTarballUrl),
         updateChannel: parsed.updateChannel === 'preview' ? 'preview' : 'stable',
         terminalSizingMode: parsed.terminalSizingMode === 'fit' ? 'fit' : 'measured',
     };
@@ -272,6 +290,18 @@ export function getConfigDir(): string {
     return dir;
 }
 
+/**
+ * Get the daemon runtime data directory (~/.adhdev/daemon/).
+ * Distinct from the user-config dir so runtime state can be cleared independently.
+ */
+export function getDaemonDataDir(): string {
+    const dir = join(getConfigDir(), 'daemon');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+
 /**
  * Get the config file path
  */