@deepseek-harness-tui/dsh-tui 0.7.0 → 0.7.2

package/lib/types/dsh-adapter/sessions/frames.js

@@ -0,0 +1,246 @@
+/**
+ * Bounded reads over the JSONL backend's concatenated-Zstandard session logs.
+ *
+ * The backend stores one session as a chain of independently decodable zstd
+ * frames — one per durable append batch — so a log grows by concatenation and
+ * never rewrites committed bytes. That container is what makes a *bounded*
+ * read possible at all: the first few frames hold the session header and its
+ * opening prompt, the last few hold whatever was appended most recently, and
+ * nothing in between has to be touched to learn either.
+ *
+ * Why this module walks frames structurally instead of scanning for the frame
+ * magic: a magic scan is a heuristic (any four bytes of compressed payload can
+ * spell `FD2FB528`), it costs a comparison per byte, and it cannot answer the
+ * one question a bounded reader must ask — "is the frame at the end of my
+ * window complete, or did I cut it in half?". Walking the frame header and its
+ * block chain, as RFC 8878 §3.1.1 defines them, answers that exactly and jumps
+ * frame-to-frame instead of byte-to-byte. Measured over a real 31 MB corpus of
+ * 49 logs and 75,263 frames: identical frame set to a magic scan, zero false
+ * positives, and 4× faster (51 ms vs 215 ms).
+ *
+ * Why not the backend's own `scanZstdFrames`: it exists, but the package's
+ * `exports` map publishes only the service class, so reaching it would mean
+ * importing through `lib/` past the export map — coupling to a private path
+ * that upstream is free to move. The frame container is a published format
+ * (RFC 8878), so re-deriving the walk against the spec is the stable choice.
+ *
+ * Why not Node's own zstd APIs: both `zstdDecompressSync` and
+ * `createZstdDecompress` stop at the end of the FIRST frame — a 4.2 MB,
+ * 14k-event log decodes to exactly one line through either. They decode a
+ * frame; they do not traverse a chain.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/sessions/frames
+ */
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { zstdDecompressSync } from 'node:zlib';
+/** Zstandard frame magic, little-endian (RFC 8878 §3.1.1.1). */
+const ZSTD_MAGIC = 0xfd2fb528;
+/**
+ * Locate the end of the frame starting at `start`, without decompressing it.
+ *
+ * The walk reads the Frame_Header (descriptor, optional window/dictionary/
+ * content-size fields) and then each Block_Header in turn — a 3-byte
+ * little-endian word carrying `last_block` (1 bit), `block_type` (2 bits) and
+ * `block_size` (21 bits) — until the block marked last. A `Reserved` block
+ * type means these bytes are not a frame at all, which is how a coincidental
+ * magic gets rejected.
+ *
+ * @param buffer - Bytes available to the reader (may end mid-frame).
+ * @param start - Offset of the candidate frame's magic.
+ * @returns The frame's exclusive end offset, or -1 when the bytes at `start`
+ *   are not a structurally complete frame within `buffer`.
+ */
+export function frameEnd(buffer, start) {
+    let at = start;
+    if (at < 0 || at + 5 > buffer.length)
+        return -1;
+    if (buffer.readUInt32LE(at) !== ZSTD_MAGIC)
+        return -1;
+    at += 4;
+    const descriptor = buffer[at];
+    at += 1;
+    const contentSizeFlag = descriptor >> 6;
+    const singleSegment = (descriptor >> 5) & 1;
+    const hasChecksum = (descriptor >> 2) & 1;
+    const dictionaryIdFlag = descriptor & 3;
+    // Window_Descriptor is present only when the frame is not single-segment.
+    if (singleSegment === 0)
+        at += 1;
+    at += [0, 1, 2, 4][dictionaryIdFlag];
+    // Frame_Content_Size: absent (0) unless single-segment, where it is 1 byte.
+    at += contentSizeFlag === 0 ? singleSegment : [0, 2, 4, 8][contentSizeFlag];
+    if (at > buffer.length)
+        return -1;
+    for (;;) {
+        if (at + 3 > buffer.length)
+            return -1;
+        const header = buffer[at] | (buffer[at + 1] << 8) | (buffer[at + 2] << 16);
+        at += 3;
+        const isLast = header & 1;
+        const blockType = (header >> 1) & 3;
+        const blockSize = header >>> 3;
+        // 3 = Reserved. Never emitted by an encoder, so this is not a frame.
+        if (blockType === 3)
+            return -1;
+        // An RLE block stores one byte and repeats it `blockSize` times; Raw and
+        // Compressed blocks store `blockSize` bytes verbatim.
+        at += blockType === 1 ? 1 : blockSize;
+        if (at > buffer.length)
+            return -1;
+        if (isLast === 1)
+            break;
+    }
+    if (hasChecksum === 1)
+        at += 4;
+    return at <= buffer.length ? at : -1;
+}
+/**
+ * Walk complete frames forward from `from`.
+ *
+ * @param buffer - Bytes to walk.
+ * @param from - Offset to start at (must be a frame boundary).
+ * @param maxFrames - Stop after this many frames; the reader's cost ceiling.
+ * @returns Complete frames in file order. A window that ends mid-frame simply
+ *   yields one fewer frame — the partial tail is never reported as complete.
+ */
+export function walkFrames(buffer, from = 0, maxFrames = Number.POSITIVE_INFINITY) {
+    const frames = [];
+    let at = from;
+    while (at < buffer.length && frames.length < maxFrames) {
+        const end = frameEnd(buffer, at);
+        if (end < 0)
+            break;
+        frames.push({ start: at, end });
+        at = end;
+    }
+    return frames;
+}
+/**
+ * Re-synchronize on a frame boundary inside a window that starts mid-frame.
+ *
+ * A tail window has no boundary to start from, so the only anchor is the one
+ * structural fact we know about the whole file: its last frame ends exactly at
+ * EOF. Every magic candidate is tried in file order, and the first one whose
+ * frame chain lands precisely on the window's end is the true boundary — a
+ * coincidental magic would have to spell a valid block chain of exactly the
+ * right total length to be mistaken for one.
+ *
+ * @param buffer - A window whose last byte is the file's last byte.
+ * @returns Frames from the earliest recoverable boundary, or [] when the
+ *   window holds no complete frame.
+ */
+export function resyncFrames(buffer) {
+    for (let at = 0; at + 4 <= buffer.length; at++) {
+        if (buffer.readUInt32LE(at) !== ZSTD_MAGIC)
+            continue;
+        const frames = walkFrames(buffer, at);
+        const last = frames[frames.length - 1];
+        if (last !== undefined && last.end === buffer.length)
+            return frames;
+    }
+    return [];
+}
+/**
+ * Decode frames to JSON log lines, tolerantly.
+ *
+ * A frame that fails to decompress or a line that fails to parse is skipped
+ * rather than thrown: a log being appended to right now can hold a frame
+ * flushed without its final checksum, and a torn tail is the backend's own
+ * documented recovery case. A picker label is read-only UI state — degrading
+ * to a fallback title beats refusing to list the session.
+ *
+ * @param buffer - Bytes the frames index into.
+ * @param frames - Complete frame ranges within `buffer`.
+ * @returns Parsed envelopes in log order.
+ */
+export function decodeFrames(buffer, frames) {
+    const lines = [];
+    for (const frame of frames) {
+        let text;
+        try {
+            text = zstdDecompressSync(buffer.subarray(frame.start, frame.end)).toString('utf8');
+        }
+        catch {
+            continue; // incomplete flush or torn frame — the rest of the log stands
+        }
+        for (const line of text.split('\n')) {
+            if (line.length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    lines.push(parsed);
+                }
+            }
+            catch {
+                // A half-written line at the tail; earlier lines remain valid.
+            }
+        }
+    }
+    return lines;
+}
+/**
+ * Size and mtime of a log, or undefined when it is gone.
+ * @param path - Absolute artifact path.
+ */
+export function fileFacts(path) {
+    try {
+        const stats = statSync(path);
+        return { bytes: stats.size, modifiedAt: stats.mtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read a window from one end of a file without loading the whole thing.
+ *
+ * @param path - Absolute artifact path.
+ * @param bytes - Window budget; the whole file is read when it is smaller.
+ * @param end - Read the last `bytes` instead of the first.
+ * @returns The window, plus whether it covers the entire file (which tells a
+ *   head reader that its last frame cannot be truncated).
+ */
+export function readWindow(path, bytes, end = false) {
+    const facts = fileFacts(path);
+    if (facts === undefined)
+        return undefined;
+    const length = Math.min(bytes, facts.bytes);
+    if (length === 0)
+        return { buffer: Buffer.alloc(0), whole: true };
+    const buffer = Buffer.alloc(length);
+    let handle;
+    try {
+        handle = openSync(path, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    let read;
+    try {
+        read = readSync(handle, buffer, 0, length, end ? facts.bytes - length : 0);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(handle);
+    }
+    // A short read is not an error: the frame walk simply sees fewer bytes and
+    // reports one fewer complete frame. Reporting `whole` honestly is what
+    // matters — a tail reader must know whether it may assume a boundary.
+    return { buffer: read === length ? buffer : buffer.subarray(0, read), whole: read === facts.bytes };
+}
+/**
+ * Decode a window read from the END of a file.
+ *
+ * A tail window has no frame boundary to start from unless it happens to
+ * cover the whole file, so it re-synchronizes; a whole-file window is simply
+ * walked.
+ *
+ * @param window - A window whose last byte is the file's last byte.
+ * @returns Log lines from the trailing frames, oldest first.
+ */
+export function decodeTail(window) {
+    return decodeFrames(window.buffer, window.whole ? walkFrames(window.buffer) : resyncFrames(window.buffer));
+}

package/lib/types/dsh-adapter/sessions/header.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Reading the persistence header — total functions over foreign data.
+ *
+ * `sessionPersistence.list()` is a service resolved from the running context,
+ * so its results are foreign values that happen to be typed. Every accessor
+ * here therefore narrows structurally and returns a fallback rather than
+ * throwing: one malformed header must cost that session its metadata, never
+ * the whole listing. This mirrors the discipline the trajectory guards already
+ * apply to session events.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/sessions/header
+ */
+import type { SessionKind } from './types.js';
+/** The header fields this feature reads, all optional at runtime. */
+export interface RawSessionHeader {
+    readonly id: string;
+    readonly cwd: string | undefined;
+    readonly createdAt: number | undefined;
+    readonly parentSession: string | undefined;
+    readonly origin: string | undefined;
+    readonly delegationDepth: number | undefined;
+    readonly seedLength: number | undefined;
+    readonly agentPreset: string | undefined;
+}
+/**
+ * Narrow one listed header.
+ *
+ * @param value - A header as the persistence service returned it.
+ * @returns The fields this feature uses, or undefined when the value carries
+ *   no usable session id — the one field nothing can substitute for.
+ */
+export declare function readHeader(value: unknown): RawSessionHeader | undefined;
+/**
+ * Decide what a session is, from its header alone.
+ *
+ * Precedence is `origin` first, lineage second, and that order is the whole
+ * correctness argument: a `/rewind` fork records `parentSession` exactly like
+ * a delegated run does, and only `origin` separates them. Upstream documents
+ * `origin` as "coarse product classification for a session created as a
+ * subagent child … presentation metadata", which is precisely this decision.
+ *
+ * `delegationDepth` is optional upstream, so a sub-agent whose header omits it
+ * is reported at depth 1: it is a delegated child by `origin`, and 1 is the
+ * shallowest depth that can be.
+ *
+ * @param header - A narrowed header.
+ * @returns The session's kind.
+ */
+export declare function classify(header: RawSessionHeader): SessionKind;
+//# sourceMappingURL=header.d.ts.map

package/lib/types/dsh-adapter/sessions/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/sessions/header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC;AAYD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAevE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAY9D"}

package/lib/types/dsh-adapter/sessions/header.js

@@ -0,0 +1,62 @@
+/** A finite number, or undefined for anything else (NaN and ±Infinity included). */
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** A non-empty string, or undefined. */
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * Narrow one listed header.
+ *
+ * @param value - A header as the persistence service returned it.
+ * @returns The fields this feature uses, or undefined when the value carries
+ *   no usable session id — the one field nothing can substitute for.
+ */
+export function readHeader(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const id = text(record['id']);
+    if (id === undefined)
+        return undefined;
+    return {
+        id,
+        cwd: text(record['cwd']),
+        createdAt: finiteNumber(record['createdAt']),
+        parentSession: text(record['parentSession']),
+        origin: text(record['origin']),
+        delegationDepth: finiteNumber(record['delegationDepth']),
+        seedLength: finiteNumber(record['seedLength']),
+        agentPreset: text(record['agentPreset']),
+    };
+}
+/**
+ * Decide what a session is, from its header alone.
+ *
+ * Precedence is `origin` first, lineage second, and that order is the whole
+ * correctness argument: a `/rewind` fork records `parentSession` exactly like
+ * a delegated run does, and only `origin` separates them. Upstream documents
+ * `origin` as "coarse product classification for a session created as a
+ * subagent child … presentation metadata", which is precisely this decision.
+ *
+ * `delegationDepth` is optional upstream, so a sub-agent whose header omits it
+ * is reported at depth 1: it is a delegated child by `origin`, and 1 is the
+ * shallowest depth that can be.
+ *
+ * @param header - A narrowed header.
+ * @returns The session's kind.
+ */
+export function classify(header) {
+    if (header.origin === 'subagent') {
+        return {
+            kind: 'subagent',
+            parent: header.parentSession,
+            depth: header.delegationDepth ?? 1,
+        };
+    }
+    if (header.parentSession !== undefined) {
+        return { kind: 'fork', parent: header.parentSession };
+    }
+    return { kind: 'root' };
+}

package/lib/types/dsh-adapter/sessions/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Persisted-session metadata — the adapter-side barrel.
+ *
+ * This directory is the only part of the session browser allowed to know how
+ * sessions are stored: the persistence service's shape, the log's frame
+ * container, the header's lineage fields. The browser screen and its
+ * components are pure UI over the types re-exported here and never touch a
+ * session log directly, which is what `verify-adapter-boundary` enforces.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/sessions
+ */
+export { classify, readHeader, type RawSessionHeader } from './header.js';
+export { digestSession, previewSession } from './digest.js';
+export { listSummaries, locateSession, type SessionSource } from './list.js';
+export { noteBranch, readIndex, writeIndex, type IndexEntry, type SessionIndex } from './store.js';
+export type { PreviewEntry, SessionDigest, SessionKind, SessionSummary, SessionTitle, TitleSource, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/dsh-adapter/sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/sessions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEzE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE3D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAE5E,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAElG,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/lib/types/dsh-adapter/sessions/index.js

@@ -0,0 +1,15 @@
+/**
+ * Persisted-session metadata — the adapter-side barrel.
+ *
+ * This directory is the only part of the session browser allowed to know how
+ * sessions are stored: the persistence service's shape, the log's frame
+ * container, the header's lineage fields. The browser screen and its
+ * components are pure UI over the types re-exported here and never touch a
+ * session log directly, which is what `verify-adapter-boundary` enforces.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/sessions
+ */
+export { classify, readHeader } from './header.js';
+export { digestSession, previewSession } from './digest.js';
+export { listSummaries, locateSession } from './list.js';
+export { noteBranch, readIndex, writeIndex } from './store.js';

package/lib/types/dsh-adapter/sessions/list.d.ts

@@ -0,0 +1,41 @@
+import type { SessionSummary } from './types.js';
+/**
+ * The slice of `ctx.sessionPersistence` this module uses.
+ *
+ * Structural and fully optional: the service is resolved from a running
+ * context whose packages may be a version apart from ours, and a listing that
+ * degrades is worth more than one that throws.
+ */
+export interface SessionSource {
+    /** Headers plus per-log change tokens — the contract built for this. */
+    listSnapshots?: (signal?: AbortSignal) => Promise<readonly unknown[]>;
+    /** Headers alone, for a backend or version without snapshots. */
+    list?: (signal?: AbortSignal) => Promise<readonly unknown[]>;
+    /** Absolute artifact path for one header; absent for storeless backends. */
+    locate?: (meta: unknown) => unknown;
+}
+/**
+ * Read every stored session into a complete summary.
+ *
+ * @param source - The persistence service.
+ * @param signal - Optional cancellation for the backend's own listing work.
+ * @returns One summary per stored session, most recently active first. No
+ *   filtering of any kind is applied — sub-agent runs and sessions with no
+ *   conversation are present and labelled as such.
+ */
+export declare function listSummaries(source: SessionSource, signal?: AbortSignal): Promise<readonly SessionSummary[]>;
+/**
+ * Resolve one session's artifact path.
+ *
+ * Listing headers is a first-line-only read per log — about 2 ms across a
+ * fifty-session history — so the preview pane resolves its target this way
+ * rather than making every summary carry a filesystem path it has no business
+ * knowing about.
+ *
+ * @param source - The persistence service.
+ * @param sessionId - Session to locate.
+ * @returns The absolute artifact path, or undefined when the backend owns no
+ *   per-session file or the session is gone.
+ */
+export declare function locateSession(source: SessionSource, sessionId: string, signal?: AbortSignal): Promise<string | undefined>;
+//# sourceMappingURL=list.d.ts.map

package/lib/types/dsh-adapter/sessions/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/sessions/list.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;IACrE,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;IAC5D,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAA;CACpC;AA0ED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CA8FpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B"}

package/lib/types/dsh-adapter/sessions/list.js

@@ -0,0 +1,213 @@
+/**
+ * Building the session list.
+ *
+ * One resolution path produces one complete, honestly-classified record per
+ * stored session — every kind, empties included — and callers decide what to
+ * show. That split is deliberate: the old picker filtered while it resolved,
+ * so "hide sub-agent runs" and "resolve a title" were the same pass and
+ * neither could change without disturbing the other. Here the browser can
+ * toggle sub-agent runs into view, or offer to clean up boot artifacts,
+ * without re-deriving anything.
+ *
+ * Cost: one `stat` per session always, plus one bounded log read per session
+ * whose revision moved since the last listing. On a warm index that is zero
+ * log reads. The path this replaces decompressed every frame of the twenty
+ * most recent logs on every open — 3.9 s over a 31 MB history.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/sessions/list
+ */
+import { basename } from 'node:path';
+import { digestSession } from './digest.js';
+import { fileFacts } from './frames.js';
+import { classify, readHeader } from './header.js';
+import { findSessionLogFile } from '../compat/sessionLog.js';
+import { readIndex, writeIndex } from './store.js';
+import { readLastUsed } from '../../sessionHistory.js';
+/** Pull `{ header, revision }` out of one `listSnapshots()` element. */
+function readSnapshot(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const raw = record['header'];
+    const header = readHeader(raw);
+    if (header === undefined)
+        return undefined;
+    const revision = record['revision'];
+    return { header, raw, revision: typeof revision === 'string' ? revision : undefined };
+}
+/**
+ * Enumerate stored sessions.
+ *
+ * Prefers `listSnapshots()` because its revision is the backend's own answer
+ * to "has this log changed", and falls back to `list()` when the resolved
+ * service predates it — in which case the change token is derived from the
+ * file's own size and mtime further down. Both are honest change tokens for an
+ * append-only log; only the authority differs.
+ */
+async function enumerate(source, signal) {
+    if (typeof source.listSnapshots === 'function') {
+        const snapshots = await source.listSnapshots(signal);
+        return snapshots.map(readSnapshot).filter((entry) => entry !== undefined);
+    }
+    if (typeof source.list === 'function') {
+        const headers = await source.list(signal);
+        return headers
+            .map((raw) => {
+            const header = readHeader(raw);
+            return header === undefined ? undefined : { header, raw, revision: undefined };
+        })
+            .filter((entry) => entry !== undefined);
+    }
+    return [];
+}
+/**
+ * Absolute artifact path for one session.
+ *
+ * The backend's own `locate()` is authoritative and is asked first. The
+ * fallback scans the session roots for the id, which is what the compat layer
+ * has always done and is deliberately independent of the backend's
+ * workspace-key scheme — so a runtime whose persistence service predates
+ * `locate`, or whose key sanitization changes, still resolves.
+ *
+ * A backend that stores no per-session artifact (SQLite) answers neither, and
+ * its sessions are summarized from their headers alone.
+ */
+function locate(source, raw, sessionId) {
+    if (typeof source.locate === 'function') {
+        let location;
+        try {
+            location = source.locate(raw);
+        }
+        catch {
+            location = undefined;
+        }
+        if (location !== null && typeof location === 'object') {
+            const path = location['path'];
+            if (typeof path === 'string' && path.length > 0)
+                return path;
+        }
+    }
+    return findSessionLogFile(sessionId);
+}
+/**
+ * Read every stored session into a complete summary.
+ *
+ * @param source - The persistence service.
+ * @param signal - Optional cancellation for the backend's own listing work.
+ * @returns One summary per stored session, most recently active first. No
+ *   filtering of any kind is applied — sub-agent runs and sessions with no
+ *   conversation are present and labelled as such.
+ */
+export async function listSummaries(source, signal) {
+    let listed;
+    try {
+        listed = await enumerate(source, signal);
+    }
+    catch {
+        return [];
+    }
+    // Children are counted from the same listing rather than by walking logs:
+    // lineage lives in the header, so a parent's sub-agent count is free.
+    const children = new Map();
+    for (const entry of listed) {
+        if (entry.header.origin !== 'subagent')
+            continue;
+        const parent = entry.header.parentSession;
+        if (parent === undefined)
+            continue;
+        children.set(parent, (children.get(parent) ?? 0) + 1);
+    }
+    const index = readIndex();
+    const next = new Map();
+    const lastUsed = readLastUsed();
+    let changed = false;
+    const summaries = [];
+    for (const { header, raw, revision } of listed) {
+        const cached = index.get(header.id);
+        const path = locate(source, raw, header.id);
+        const facts = path === undefined ? undefined : fileFacts(path);
+        // Falls back to the file's own identity when the backend offered no token.
+        const token = revision ?? (facts === undefined ? undefined : `${facts.bytes}:${facts.modifiedAt}`);
+        let derived;
+        if (cached?.derived !== undefined && token !== undefined && cached.derived.revision === token) {
+            derived = cached.derived;
+        }
+        else if (path !== undefined && token !== undefined) {
+            const digest = digestSession(path, header.cwd ?? '');
+            derived = {
+                revision: token,
+                title: digest.title?.text ?? '',
+                titleSource: digest.title?.source ?? 'fallback',
+                hasPrompt: digest.hasPrompt,
+                model: digest.model,
+                label: digest.label,
+            };
+            changed = true;
+        }
+        // Carry every entry that holds anything worth keeping — including a pure
+        // cache hit, which must survive into the next index or the following
+        // listing would re-derive everything it just reused.
+        if (derived !== undefined || cached?.branch !== undefined) {
+            next.set(header.id, { derived, branch: cached?.branch });
+        }
+        const createdAt = header.createdAt ?? facts?.modifiedAt ?? 0;
+        summaries.push({
+            id: header.id,
+            kind: classify(header),
+            title: {
+                text: derived?.title !== undefined && derived.title.length > 0
+                    ? derived.title
+                    : basename(header.cwd ?? '') || header.id.slice(0, 8),
+                source: derived?.titleSource ?? 'fallback',
+            },
+            cwd: header.cwd ?? '',
+            createdAt,
+            updatedAt: Math.max(facts?.modifiedAt ?? 0, lastUsed[header.id] ?? 0, createdAt),
+            bytes: facts?.bytes,
+            // Without a readable artifact nothing can be proven empty, and hiding a
+            // real session is the worse error — so an unreadable log is listed.
+            hasPrompt: derived?.hasPrompt ?? true,
+            agentPreset: header.agentPreset,
+            model: derived?.model,
+            label: derived?.label,
+            branch: cached?.branch,
+            childCount: children.get(header.id) ?? 0,
+        });
+    }
+    // Entries for sessions the backend no longer lists are dropped here; that is
+    // the whole of the cache's garbage collection, and it runs on every listing.
+    if (changed || next.size !== index.size)
+        writeIndex(next);
+    // A total order, not just a sort key. `updatedAt` is dominated by the log's
+    // mtime, and sessions written inside the same millisecond tie on it — which
+    // would leave their relative order down to whatever the backend happened to
+    // enumerate first, so the same history could list differently twice in a
+    // row. Creation time breaks the tie, and the id breaks that.
+    return summaries.sort((left, right) => right.updatedAt - left.updatedAt ||
+        right.createdAt - left.createdAt ||
+        (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+}
+/**
+ * Resolve one session's artifact path.
+ *
+ * Listing headers is a first-line-only read per log — about 2 ms across a
+ * fifty-session history — so the preview pane resolves its target this way
+ * rather than making every summary carry a filesystem path it has no business
+ * knowing about.
+ *
+ * @param source - The persistence service.
+ * @param sessionId - Session to locate.
+ * @returns The absolute artifact path, or undefined when the backend owns no
+ *   per-session file or the session is gone.
+ */
+export async function locateSession(source, sessionId, signal) {
+    let listed;
+    try {
+        listed = await enumerate(source, signal);
+    }
+    catch {
+        return undefined;
+    }
+    const match = listed.find(entry => entry.header.id === sessionId);
+    return match === undefined ? undefined : locate(source, match.raw, sessionId);
+}