dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-compound/scripts/session-history/discover-sessions.sh

@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# Discover session files for DeepSeek Harness (dsh). The other platform probes
+# (Claude Code, Codex, Cursor, Pi, oh-my-pi) are kept as optional fallbacks for
+# mixed-tool repos; the extraction scripts downstream only decode dsh sessions,
+# so run the documented pipeline with `--platform dsh`.
+#
+# Usage: discover-sessions.sh <repo-name> <days> [--cwd /abs/repo/root] [--platform dsh|claude|codex|cursor|pi|omp]
+#
+# Outputs one file path per line. Safe in both bash and zsh (all globs guarded).
+# Pass output to extract-metadata.py:
+#   bash discover-sessions.sh <repo-name> 7 --platform dsh --cwd /abs/repo/root \
+#     | tr '\n' '\0' | xargs -0 python3 extract-metadata.py --cwd-filter <repo-name>
+#
+# Arguments:
+#   repo-name  Folder name of the repo (e.g., "my-repo"). Used for directory matching.
+#   days       Scan window in days (e.g., 7). Files older than this are skipped.
+#   --cwd      Absolute repo root. Used for exact dsh (and Pi/omp) encoded-CWD
+#              discovery and the omp raw-bucket probe. Claude listing is unfiltered;
+#              extract-metadata.py --cwd-filter matches recorded cwd.
+#   --platform Restrict to a single platform. Omit to search all.
+
+set -euo pipefail
+
+REPO_NAME="${1:?Usage: discover-sessions.sh <repo-name> <days> [--cwd /abs/repo/root] [--platform claude|codex|cursor|pi|omp|dsh]}"
+DAYS="${2:?Usage: discover-sessions.sh <repo-name> <days> [--cwd /abs/repo/root] [--platform claude|codex|cursor|pi|omp|dsh]}"
+PLATFORM="all"
+REPO_CWD=""
+
+# Parse optional --platform flag
+shift 2
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --cwd) REPO_CWD="$2"; shift 2 ;;
+        --platform) PLATFORM="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+encode_pi_cwd() {
+    local cwd="${1%/}"
+    local encoded="${cwd//\//-}"
+    encoded="${encoded#-}"
+    printf -- "--%s--" "$encoded"
+}
+
+# --- Claude Code ---
+# List every recent jsonl under <config-dir>/projects. Folder names are an
+# undocumented encoder of session CWD; do not invert them. Repo attribution
+# is the recorded `cwd` field, applied by extract-metadata.py --cwd-filter.
+# CLAUDE_CONFIG_DIR relocates the whole config tree (official); unset -> ~/.claude.
+discover_claude() {
+    local base="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"
+    [ -d "$base" ] || return 0
+    find "$base" -mindepth 2 -maxdepth 2 -type f -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+}
+
+# --- Codex ---
+discover_codex() {
+    local codex_home="${CODEX_HOME:-$HOME/.codex}"
+    for base in "$codex_home/sessions" "$HOME/.agents/sessions"; do
+        [ -d "$base" ] || continue
+
+        # Use mtime-based discovery (consistent with Claude/Cursor) so that
+        # sessions started before the scan window but still active within it
+        # are not missed.
+        find "$base" -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- Cursor ---
+discover_cursor() {
+    local base="$HOME/.cursor/projects"
+    [ -d "$base" ] || return 0
+
+    for dir in "$base"/*"$REPO_NAME"*/; do
+        [ -d "$dir" ] || continue
+        local transcripts="$dir/agent-transcripts"
+        [ -d "$transcripts" ] || continue
+        find "$transcripts" -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- Pi ---
+discover_pi() {
+    local agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+    local base="${PI_CODING_AGENT_SESSION_DIR:-$agent_dir/sessions}"
+    [ -d "$base" ] || return 0
+
+    # Pi's explicit session-dir override stores session files directly in the
+    # supplied directory. The cwd filter later reads each header and keeps only
+    # sessions for the active repo.
+    if [ -n "${PI_CODING_AGENT_SESSION_DIR:-}" ]; then
+        find "$base" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+        if [ -z "$REPO_CWD" ]; then
+            for dir in "$base"/*"$REPO_NAME"*/; do
+                [ -d "$dir" ] || continue
+                find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+            done
+        fi
+        return 0
+    fi
+
+    # Pi stores sessions under --<absolute-cwd-with-slashes-as-hyphens>--.
+    # When the caller supplies an exact repo root, probe only that encoded
+    # directory so sibling repos like my-repo-old never enter the pipeline.
+    if [ -n "$REPO_CWD" ]; then
+        local dir="$base/$(encode_pi_cwd "$REPO_CWD")"
+        [ -d "$dir" ] || return 0
+        find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+        return 0
+    fi
+
+    # Fallback for direct script use without --cwd.
+    for dir in "$base"/*"$REPO_NAME"*/; do
+        [ -d "$dir" ] || continue
+        find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- oh-my-pi (omp) ---
+# Encode omp's raw bucket name for a cwd: home-relative "-<rel>",
+# tmp-relative "-tmp-<rel>", and otherwise "--<abs>--", with path separators
+# and ":" encoded as "-" (session-paths.ts getDefaultSessionDirName /
+# encodeLegacyAbsoluteSessionDirName). This raw scheme predates the hashed
+# scheme and is current again since omp 17.2.9 (#7646 restored it and removed
+# automatic migration), so buckets in the wild use both shapes. Canonicalize
+# with physical paths so symlinked cwds resolve to the same bucket, mirroring
+# omp's resolveEquivalentPath. Prints nothing when the cwd cannot be resolved.
+encode_omp_raw_cwd() {
+    local cwd canon_home canon_tmp rel
+    cwd="$(cd "$1" 2>/dev/null && pwd -P)" || return 0
+    canon_home="$(cd "$HOME" 2>/dev/null && pwd -P)" || canon_home="$HOME"
+    case "$cwd" in
+        "$canon_home")
+            printf -- '-'
+            ;;
+        "$canon_home"/*)
+            rel="$(printf '%s' "${cwd#"$canon_home"/}" | sed 's/[/\\:]/-/g')"
+            printf -- '-%s' "$rel"
+            ;;
+        *)
+            canon_tmp="$(cd "${TMPDIR:-/tmp}" 2>/dev/null && pwd -P)" || canon_tmp=""
+            case "$cwd" in
+                "$canon_tmp")
+                    printf -- '-tmp'
+                    ;;
+                "$canon_tmp"/*)
+                    rel="$(printf '%s' "${cwd#"$canon_tmp"/}" | sed 's/[/\\:]/-/g')"
+                    printf -- '-tmp-%s' "$rel"
+                    ;;
+                *)
+                    rel="$(printf '%s' "${cwd#/}" | sed 's/[/\\:]/-/g')"
+                    printf -- '--%s--' "$rel"
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+discover_omp() {
+    local config_dir="${PI_CONFIG_DIR:-.omp}"
+
+    # omp's explicit session-dir override stores session files directly in the
+    # supplied directory (flat), mirroring Pi's override branch. The cwd filter
+    # later reads each header and keeps only sessions for the active repo.
+    if [ -n "${PI_CODING_AGENT_SESSION_DIR:-}" ]; then
+        local base="$PI_CODING_AGENT_SESSION_DIR"
+        [ -d "$base" ] || return 0
+        find "$base" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+        if [ -z "$REPO_CWD" ]; then
+            for dir in "$base"/*"$REPO_NAME"*/; do
+                [ -d "$dir" ] || continue
+                find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+            done
+        fi
+        return 0
+    fi
+
+    # omp has two bucket-naming schemes in the wild, and both keep the raw
+    # repo basename (spaces and all) inside the bucket name:
+    #   - raw: "-<home-rel>", "-tmp-<tmp-rel>", "--<abs>--" (legacy relative to
+    #     the hashed scheme; restored as current in omp 17.2.9, #7646)
+    #   - hashed: "<scope>-<sanitized-basename>-<sha256-of-canonical-cwd>"
+    #     (intermediate releases; basename runs of [^a-zA-Z0-9._-] collapse to
+    #     "-", edge dashes stripped, capped at the last 80 chars, empty falls
+    #     back to "project" — session-paths.ts getDefaultSessionDirName)
+    # Scan basename-matching buckets in the default-profile sessions root and
+    # in every named-profile root; exact repo attribution comes from the
+    # downstream header `cwd` filter (extract-metadata.py --cwd-filter reads
+    # the type:"session" header). Glob the sanitized form so repos whose
+    # basename contains characters the hashed scheme normalizes (e.g. spaces)
+    # still match, and glob the raw form so raw-scheme buckets whose basename
+    # sanitizes differently (e.g. "my repo" in "--Users-test-Code-my repo--")
+    # are found too. When --cwd is supplied, also probe the exact raw bucket
+    # name: it catches buckets the basename globs miss when the bucket's path
+    # segments no longer resemble the repo name as typed.
+    local sanitized
+    sanitized="$(printf '%s' "$REPO_NAME" | sed -E 's/[^a-zA-Z0-9._-]+/-/g; s/^-+//; s/-+$//' | tail -c 80)"
+    [ -n "$sanitized" ] || sanitized="project"
+    local agent_dir="${PI_CODING_AGENT_DIR:-$HOME/$config_dir/agent}"
+    # omp getSessionsDir() flattens the agent/ prefix under XDG: ~/.omp/agent/sessions
+    # becomes $XDG_DATA_HOME/omp/sessions (and $XDG_DATA_HOME/omp/profiles/<name>/sessions).
+    # Only linux/darwin, only when XDG_DATA_HOME is set and the omp app root exists,
+    # and only when PI_CODING_AGENT_DIR did not already take over the agent root.
+    local xdg_omp=""
+    if [ -z "${PI_CODING_AGENT_DIR:-}" ] && [ -n "${XDG_DATA_HOME:-}" ]; then
+        case "$(uname -s)" in
+            Linux|Darwin)
+                if [ -d "${XDG_DATA_HOME%/}/omp" ]; then
+                    xdg_omp="${XDG_DATA_HOME%/}/omp"
+                fi
+                ;;
+        esac
+    fi
+    {
+        local root dir encoded
+        if [ -n "$REPO_CWD" ]; then
+            encoded="$(encode_omp_raw_cwd "$REPO_CWD")"
+            if [ -n "$encoded" ]; then
+                for root in "$agent_dir/sessions" \
+                            "$HOME/$config_dir"/profiles/*/agent/sessions \
+                            ${xdg_omp:+"$xdg_omp/sessions"} \
+                            ${xdg_omp:+"$xdg_omp"/profiles/*/sessions}; do
+                    [ -d "$root/$encoded" ] || continue
+                    find "$root/$encoded" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+                done
+            fi
+        fi
+        for root in "$agent_dir/sessions" \
+                    "$HOME/$config_dir"/profiles/*/agent/sessions \
+                    ${xdg_omp:+"$xdg_omp/sessions"} \
+                    ${xdg_omp:+"$xdg_omp"/profiles/*/sessions}; do
+            [ -d "$root" ] || continue
+            for dir in "$root"/*"$sanitized"*/; do
+                [ -d "$dir" ] || continue
+                find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+            done
+            if [ "$REPO_NAME" != "$sanitized" ]; then
+                for dir in "$root"/*"$REPO_NAME"*/; do
+                    [ -d "$dir" ] || continue
+                    find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+                done
+            fi
+        done
+    # The probe and the globs can hit the same bucket; emit each path once.
+    } | awk '!seen[$0]++'
+}
+
+# --- DeepSeek Harness (dsh) ---
+# dsh stores one zstd-compressed jsonl per session under
+#   <DSH_HOME>/sessions/--<projectKey(cwd)>--/<session-id>/session[.v<N>].jsonl.zstd
+# The bucket name is dsh's own reversible-ish encoding of the project cwd, which
+# bash cannot reproduce faithfully (separator runs collapse, rare code units
+# become ~XXXX). Delegate discovery to discover_dsh.py so the encoder lives in
+# exactly one place and stays in sync with the reader.
+discover_dsh() {
+    local here
+    here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    [ -f "$here/discover_dsh.py" ] || return 0
+    local py
+    py="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"
+    [ -n "$py" ] || return 0
+    if [ -n "$REPO_CWD" ]; then
+        "$py" "$here/discover_dsh.py" --cwd "$REPO_CWD" --days "$DAYS" || true
+    else
+        "$py" "$here/discover_dsh.py" --name "$REPO_NAME" --days "$DAYS" || true
+    fi
+}
+
+# --- Dispatch ---
+case "$PLATFORM" in
+    claude)  discover_claude ;;
+    codex)   discover_codex ;;
+    cursor)  discover_cursor ;;
+    pi)      discover_pi ;;
+    omp)     discover_omp ;;
+    dsh)     discover_dsh ;;
+    all)
+        # Pi and omp share the PI_CODING_AGENT_SESSION_DIR override: when it
+        # is set, both discover functions emit the same flat-dir files, and
+        # the downstream xargs call does not deduplicate. Emit each path once;
+        # platform attribution is unaffected because extract-metadata.py
+        # detects the file shape (title slot => omp, otherwise pi).
+        { discover_claude; discover_codex; discover_cursor; discover_pi; discover_omp; discover_dsh; } | awk '!seen[$0]++'
+        ;;
+    *)
+        echo "Unknown platform: $PLATFORM" >&2
+        exit 1
+        ;;
+esac

package/skills/ce-compound/scripts/session-history/discover_dsh.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Print dsh session files for one repository.
+
+dsh buckets sessions per project cwd:
+
+    <DSH_HOME>/sessions/--<projectKey(cwd)>--/<session-id>/session[.v<N>].jsonl.zstd
+
+`projectKey` collapses path separators into `-` and escapes other unsafe code
+units as `~XXXX`, which bash cannot reproduce faithfully (a `~` in a path, a
+non-ASCII directory name, or a separator run all change the bucket name). This
+helper reuses the same encoder as the reader so discovery and decoding agree.
+
+Usage:
+  discover_dsh.py --cwd /abs/repo/root --days 7
+  discover_dsh.py --name my-repo --days 7     # basename fallback
+  discover_dsh.py --list-all --days 7         # every bucket, cwd filtered later
+
+Prints one absolute path per line, newest first. Exits 0 with no output when
+nothing matches, so an empty pipeline stays a normal state.
+
+Line endings are forced to LF. Callers pipe us through `tr '\n' '\0' | xargs -0`
+(a bash pipeline, LF-delimited); Python's default text mode on Windows would
+emit CRLF and leave a stray `\r` glued to every path, which then fails the
+extension gate in the extractors as a file-not-found.
+"""
+import argparse
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import dsh_session  # noqa: E402
+
+
+def iter_session_files(directory):
+    """Yield the session artifacts inside one session directory.
+
+    A session can keep more than one artifact when a format generation was
+    migrated (`session.jsonl.zstd` -> `session.v3.jsonl.zstd` -> `session.v4...`);
+    emit only the highest generation so one session is not reported twice.
+    """
+    try:
+        names = os.listdir(directory)
+    except OSError:
+        return
+    candidates = sorted(n for n in names if dsh_session.is_session_file(os.path.join(directory, n)))
+    if not candidates:
+        return
+    # Sort by generation number so `.v4` wins over `.v3`, and a bare
+    # `session.jsonl.zstd` (generation 0) sorts first.
+    def generation(name):
+        marker = ".v"
+        if marker in name:
+            try:
+                return int(name.split(marker, 1)[1].split(".", 1)[0])
+            except (IndexError, ValueError):
+                return 0
+        return 0
+
+    newest = max(candidates, key=lambda n: (generation(n), n))
+    yield os.path.join(directory, newest)
+
+
+def recent(path, cutoff):
+    """Report whether a file's mtime falls inside the scan window."""
+    try:
+        return os.path.getmtime(path) >= cutoff
+    except OSError:
+        return False
+
+
+def main():
+    # LF-only output so the bash pipe below us sees clean paths (see module doc).
+    sys.stdout.reconfigure(newline="\n")
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--cwd", help="absolute repository root; probes its exact bucket")
+    group.add_argument("--name", help="repository folder name; matches bucket substrings")
+    group.add_argument("--list-all", action="store_true", help="scan every bucket")
+    parser.add_argument("--days", type=float, default=7.0, help="scan window in days")
+    args = parser.parse_args()
+
+    if not dsh_session.available():
+        # Python < 3.14 cannot decode dsh sessions; stay silent so the caller
+        # degrades to "no dsh sessions" instead of failing the pipeline.
+        return 0
+
+    cutoff = time.time() - args.days * 86400
+    found = []
+    for root in dsh_session.session_roots():
+        if not os.path.isdir(root):
+            continue
+        if args.list_all:
+            buckets = [os.path.join(root, n) for n in sorted(os.listdir(root))]
+        elif args.cwd:
+            buckets = [os.path.join(root, dsh_session.project_key(args.cwd))]
+        else:
+            buckets = [
+                os.path.join(root, n)
+                for n in sorted(os.listdir(root))
+                if args.name in n
+            ]
+        for bucket in buckets:
+            if not os.path.isdir(bucket):
+                continue
+            for session in sorted(os.listdir(bucket)):
+                session_dir = os.path.join(bucket, session)
+                if not os.path.isdir(session_dir):
+                    continue
+                for path in iter_session_files(session_dir):
+                    if recent(path, cutoff):
+                        found.append(path)
+
+    found.sort(key=lambda p: os.path.getmtime(p), reverse=True)
+    for path in found:
+        print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/ce-compound/scripts/session-history/dsh_session.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Read DeepSeek Harness (dsh) session files.
+
+dsh stores each session as a single `session*.jsonl.zstd` file: **concatenated
+zstd frames**, one per append. A plain `zstd -d` or `compression.zstd.decompress`
+call stops after the first frame and silently loses the rest of the session, so
+this module scans frame boundaries itself before decompressing each frame.
+
+Requires Python 3.14+ (`compression.zstd` in the standard library). Import is
+safe on older interpreters: `available()` reports whether reading will work and
+callers degrade to "no dsh sessions" instead of crashing.
+"""
+import json
+import os
+import sys
+
+try:
+    from compression import zstd as _zstd
+except ImportError:  # Python < 3.14
+    _zstd = None
+
+# zstd frame magic, little-endian 0xFD2FB528.
+ZSTD_MAGIC = 4247762216
+
+# dsh names session files `session.v<N>.jsonl.zstd` and, in older layouts,
+# `session.jsonl.zstd`. Session directories are `session-<uuid>` or a bare uuid.
+SESSION_FILE_PREFIX = "session"
+SESSION_FILE_SUFFIX = ".jsonl.zstd"
+
+
+def available():
+    """Report whether this interpreter can decompress dsh sessions."""
+    return _zstd is not None
+
+
+def is_session_file(path):
+    """Report whether a path looks like a dsh session file."""
+    base = os.path.basename(path)
+    return base.startswith(SESSION_FILE_PREFIX) and base.endswith(SESSION_FILE_SUFFIX)
+
+
+def project_key(cwd):
+    """Encode a project directory the way dsh names its session bucket.
+
+    Mirrors dsh's own `projectKey`: separators (`/`, `\\\\`, `:`) collapse into a
+    single `-` run, other unsafe code units become `~XXXX`, and the result is
+    wrapped in `--` with leading separators trimmed. Encoding the cwd exactly
+    means a repo's bucket is addressed directly instead of by fuzzy basename
+    match, so sibling repos (`my-repo` vs `my-repo-old`) never mix.
+    """
+    if not cwd:
+        raise ValueError("cannot encode an empty project path")
+    readable = ""
+    separator_run = False
+    for ch in cwd:
+        if ch in ("/", "\\", ":"):
+            if not separator_run:
+                readable += "-"
+            separator_run = True
+        elif ch != "~" and (ch.isascii() and (ch.isalnum() or ch in "._-")):
+            readable += ch
+            separator_run = False
+        else:
+            readable += "~" + format(ord(ch), "04X")
+            separator_run = False
+    trimmed = readable.lstrip("-") or "root"
+    return "--" + trimmed[:251] + "--"
+
+
+def session_roots():
+    """Return the candidate dsh session roots, most specific first.
+
+    `DSH_HOME` relocates the whole state tree; without it dsh uses `~/.dsh`.
+    """
+    home = os.environ.get("DSH_HOME") or os.path.join(os.path.expanduser("~"), ".dsh")
+    return [os.path.join(home, "sessions")]
+
+
+def scan_frames(buffer, max_frames=None):
+    """Locate concatenated zstd frames.
+
+    Walks each frame header and block list exactly as zstd frames are laid out:
+    magic, frame header descriptor, optional window/dictionary/content-size
+    fields, then blocks whose 3-byte header carries last-block, type, and size.
+
+    Returns `(frames, torn_start)` where `frames` is a list of `(start, end)`
+    byte ranges and `torn_start` is the offset of an incomplete trailing frame
+    (a crash mid-append), or None.
+    """
+    frames = []
+    offset = 0
+    limit = len(buffer)
+    while offset + 4 <= limit:
+        if max_frames is not None and len(frames) >= max_frames:
+            break
+        if int.from_bytes(buffer[offset:offset + 4], "little") != ZSTD_MAGIC:
+            # Not a frame boundary: the tail is corrupt or truncated.
+            return frames, offset
+        start = offset
+        offset += 4
+        if offset >= limit:
+            return frames, start
+        descriptor = buffer[offset]
+        offset += 1
+        if (descriptor & 24) != 0:
+            # Reserved frame-header bits set: this is not a frame boundary.
+            return frames, start
+        content_size_flag = descriptor >> 6
+        single_segment = (descriptor & 32) != 0
+        checksum = (descriptor & 4) != 0
+        dictionary_flag = descriptor & 3
+        dictionary_bytes = 4 if dictionary_flag == 3 else dictionary_flag
+        if content_size_flag == 0:
+            content_size_bytes = 1 if single_segment else 0
+        else:
+            content_size_bytes = 1 << content_size_flag
+        header_bytes = (0 if single_segment else 1) + dictionary_bytes + content_size_bytes
+        if offset + header_bytes > limit:
+            return frames, start
+        offset += header_bytes
+        while True:
+            if offset + 3 > limit:
+                return frames, start
+            header = int.from_bytes(buffer[offset:offset + 3], "little")
+            offset += 3
+            last_block = (header & 1) != 0
+            block_type = (header >> 1) & 3
+            block_size = header >> 3
+            if block_type == 3:
+                return frames, start
+            # Raw (0) and compressed (2) blocks carry block_size bytes; an RLE
+            # block carries a single byte repeated block_size times.
+            payload = 1 if block_type == 1 else block_size
+            if offset + payload > limit:
+                return frames, start
+            offset += payload
+            if last_block:
+                break
+        if checksum:
+            offset += 4
+        if offset > limit:
+            return frames, start
+        frames.append((start, offset))
+    return frames, None
+
+
+def read_lines(path, max_lines=None):
+    """Decode a dsh session file into its JSONL lines.
+
+    Emits only complete decoded frames. A torn trailing frame (interrupted
+    append) is dropped rather than failing the whole read, matching how dsh
+    itself tolerates the last partial record.
+    """
+    if _zstd is None:
+        raise RuntimeError("Python 3.14+ required: `compression.zstd` is unavailable")
+    with open(path, "rb") as handle:
+        buffer = handle.read()
+    frames, _torn = scan_frames(buffer)
+    chunks = []
+    for start, end in frames:
+        try:
+            chunks.append(_zstd.decompress(buffer[start:end]))
+        except Exception:  # noqa: BLE001 - a single bad frame must not hide the rest
+            continue
+    text = b"".join(chunks).decode("utf-8", errors="replace")
+    if max_lines is None:
+        return text.splitlines()
+    return text.splitlines()[:max_lines]
+
+
+def read_objects(path, max_lines=None):
+    """Decode a dsh session file into parsed JSON objects, skipping bad lines."""
+    objects = []
+    for line in read_lines(path, max_lines):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            objects.append(json.loads(stripped))
+        except (json.JSONDecodeError, ValueError):
+            continue
+    return objects
+
+
+def session_header(objects):
+    """Return the `type: session` header object, or None.
+
+    The header carries `id`, `cwd`, and `createdAt` (epoch milliseconds); it is
+    the first record dsh writes, so it survives any later truncation.
+    """
+    for obj in objects:
+        if isinstance(obj, dict) and obj.get("type") == "session":
+            return obj
+    return None
+
+
+def iso_from_millis(value):
+    """Format dsh's epoch-millisecond timestamps as ISO 8601 UTC."""
+    if not isinstance(value, (int, float)):
+        return ""
+    from datetime import datetime, timezone
+
+    try:
+        return datetime.fromtimestamp(value / 1000.0, tz=timezone.utc).isoformat()
+    except (OverflowError, OSError, ValueError):
+        return ""
+
+
+def content_text(blocks):
+    """Concatenate the text blocks of one dsh content array.
+
+    dsh content blocks are `{type: 'text'|'reasoning'|'tool-call'|'image', ...}`.
+    Only `text` is model- or user-authored prose; reasoning and tool calls stay
+    out so keyword scans cannot false-match tool names or inner monologue.
+    """
+    if isinstance(blocks, str):
+        return [blocks]
+    chunks = []
+    if isinstance(blocks, list):
+        for block in blocks:
+            if isinstance(block, dict) and block.get("type") == "text":
+                text = block.get("text")
+                if isinstance(text, str):
+                    chunks.append(text)
+    return chunks