@procrastivity/clast 0.0.1

package/lib/clast/clast-subcommands/snapshot.bash

@@ -0,0 +1,294 @@
+# clast-subcommands/snapshot.bash — `clast snapshot`.
+#
+# Walks $(clast_projects_dir)/<segment>/<uuid>.jsonl, copies each new or
+# modified session into $(clast_journal_dir)/transcripts/<day>/<segment>/,
+# and appends one manifest line per capture. Idempotent: re-running a file
+# whose (session_id, source_mtime) is already in the manifest is a no-op.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+# shellcheck source=lib/clast/clast-manifest-lib.bash
+# shellcheck source=lib/clast/clast-decode-lib.bash
+# shellcheck source=lib/clast/clast-registry-lib.bash
+
+_clast_snapshot_usage() {
+  cat <<'EOF'
+Usage: clast snapshot [--dry-run] [--since TIMESTAMP] [--include-segment SEG]
+
+Capture new Claude Code transcripts into the journal.
+
+Flags:
+  --dry-run               Preview only; do not copy or write manifest.
+  --since TIMESTAMP       Skip sources with mtime < TIMESTAMP (ISO 8601 or
+                          any string GNU `date -d` understands; e.g. -1d).
+  --include-segment SEG   Limit scan to SEG (repeatable). Value must start
+                          with '-' (segments always do).
+  -h, --help              Print this usage and exit.
+EOF
+}
+
+# _clast_snapshot_bucket_for_epoch <epoch>
+#   Mirror of clast_today's cutoff math against an arbitrary epoch. Local
+#   time per docs/overview.md#conventions.
+_clast_snapshot_bucket_for_epoch() {
+  local epoch="$1"
+  local cutoff="${CLAST_DAY_CUTOFF:-04:00}"
+  local h="${cutoff%%:*}" m="${cutoff##*:}"
+  h=$((10#$h))
+  m=$((10#$m))
+  local off=$((h * 3600 + m * 60))
+  # GNU `date -d` — BSD date not supported, per overview.md.
+  date -d "@$((epoch - off))" +%Y-%m-%d
+}
+
+clast_cmd_snapshot() {
+  local dry_run=0
+  local since_epoch=""
+  local -a include_segments=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --dry-run)
+        dry_run=1; shift ;;
+      --since)
+        if [[ $# -lt 2 ]]; then
+          clast_log_error "snapshot: --since requires a value"; return 2
+        fi
+        if ! since_epoch="$(date -d "$2" +%s 2>/dev/null)" || [[ -z "$since_epoch" ]]; then
+          clast_log_error "snapshot: cannot parse --since '$2'"; return 2
+        fi
+        shift 2 ;;
+      --since=*)
+        local _v="${1#*=}"
+        if ! since_epoch="$(date -d "$_v" +%s 2>/dev/null)" || [[ -z "$since_epoch" ]]; then
+          clast_log_error "snapshot: cannot parse --since '$_v'"; return 2
+        fi
+        shift ;;
+      --include-segment)
+        if [[ $# -lt 2 ]]; then
+          clast_log_error "snapshot: --include-segment requires a value"; return 2
+        fi
+        if [[ "$2" != -* ]]; then
+          clast_log_error "snapshot: --include-segment value must start with '-' (got '$2')"; return 2
+        fi
+        include_segments+=("$2"); shift 2 ;;
+      --include-segment=*)
+        local _v="${1#*=}"
+        if [[ "$_v" != -* ]]; then
+          clast_log_error "snapshot: --include-segment value must start with '-' (got '$_v')"; return 2
+        fi
+        include_segments+=("$_v"); shift ;;
+      --json)
+        # Accept the global flag positionally as well, mirroring registry.
+        # Lets `clast snapshot --json` work alongside `clast --json snapshot`.
+        export CLAST_JSON=1; shift ;;
+      -h|--help)
+        _clast_snapshot_usage; return 0 ;;
+      *)
+        clast_log_error "snapshot: unknown flag '$1'"; return 2 ;;
+    esac
+  done
+
+  # Manifest precondition: cron-mode safety. clast_manifest_iterate uses
+  # fromjson? today, so most corruption is swallowed silently — this guard
+  # is the documented hook for a future strict-iterate contract (step plan
+  # task 3). Leaving it in keeps the exit-4 path wired the moment iterate
+  # learns to surface corruption.
+  local _it_rc=0
+  clast_manifest_iterate 'true' >/dev/null 2>&1 || _it_rc=$?
+  if (( _it_rc != 0 )); then
+    if [[ -n "${CLAST_JSON:-}" ]]; then
+      printf '{"error":"manifest is corrupt","code":4}\n'
+    else
+      clast_log_error "snapshot: manifest is corrupt; refusing to write"
+    fi
+    return 4
+  fi
+
+  local projects_dir journal_dir
+  projects_dir="$(clast_projects_dir)"
+  journal_dir="$(clast_journal_dir)"
+
+  local skipped=0
+  local total_bytes=0
+  local -a captured_lines=()
+  local -a error_lines=()
+  local -a captured_segments=()
+
+  # TODO(v1.1): parallel capture across segments.
+  if [[ -d "$projects_dir" ]]; then
+    local source segment session_id mtime_epoch mtime_iso source_size
+    local first_ts ts_epoch day_bucket
+    local dest_rel dest dest_dir tmp
+    while IFS= read -r -d '' source; do
+      segment="$(basename "$(dirname "$source")")"
+
+      if (( ${#include_segments[@]} > 0 )); then
+        local _hit=0 _seg
+        for _seg in "${include_segments[@]}"; do
+          if [[ "$_seg" == "$segment" ]]; then _hit=1; break; fi
+        done
+        if (( _hit == 0 )); then
+          skipped=$((skipped + 1))
+          continue
+        fi
+      fi
+
+      if ! mtime_epoch="$(stat -c %Y "$source" 2>/dev/null)" || [[ -z "$mtime_epoch" ]]; then
+        error_lines+=("$(jq -cn --arg f "$source" --arg r "stat failed" '{file:$f,reason:$r}')")
+        continue
+      fi
+
+      if [[ -n "$since_epoch" ]] && (( mtime_epoch < since_epoch )); then
+        skipped=$((skipped + 1))
+        continue
+      fi
+
+      session_id="$(basename "$source" .jsonl)"
+      if ! [[ "$session_id" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ ]]; then
+        error_lines+=("$(jq -cn --arg f "$source" --arg r "non-uuid filename" '{file:$f,reason:$r}')")
+        continue
+      fi
+
+      mtime_iso="$(date -u -d "@$mtime_epoch" +%Y-%m-%dT%H:%M:%SZ)"
+      source_size="$(stat -c %s "$source" 2>/dev/null || echo 0)"
+
+      first_ts="$(head -n1 "$source" 2>/dev/null | jq -r '.timestamp // empty' 2>/dev/null || true)"
+      if [[ -n "$first_ts" ]] && ts_epoch="$(date -d "$first_ts" +%s 2>/dev/null)" && [[ -n "$ts_epoch" ]]; then
+        day_bucket="$(_clast_snapshot_bucket_for_epoch "$ts_epoch")"
+      else
+        # --verbose only: a malformed first line shouldn't spam cron/hook logs.
+        if [[ -n "${CLAST_VERBOSE:-}" ]]; then
+          clast_log_warn "snapshot: '$source' missing first-line timestamp; falling back to mtime"
+        fi
+        day_bucket="$(_clast_snapshot_bucket_for_epoch "$mtime_epoch")"
+      fi
+
+      # Dedup on (session_id, source_mtime). Mtime — not ctime or size —
+      # is the manifest's "most recent line wins" key; Claude Code's
+      # writer bumps mtime whenever a session grows.
+      if clast_manifest_has_capture "$session_id" "$mtime_iso"; then
+        skipped=$((skipped + 1))
+        continue
+      fi
+
+      dest_rel="transcripts/$day_bucket/$segment/$session_id.jsonl"
+      dest="$journal_dir/$dest_rel"
+
+      if (( dry_run == 0 )); then
+        dest_dir="$(dirname "$dest")"
+        if ! mkdir -p "$dest_dir"; then
+          error_lines+=("$(jq -cn --arg f "$source" --arg r "mkdir failed" '{file:$f,reason:$r}')")
+          continue
+        fi
+        if ! tmp="$(mktemp "$dest.copy.XXXXXX" 2>/dev/null)"; then
+          error_lines+=("$(jq -cn --arg f "$source" --arg r "mktemp failed" '{file:$f,reason:$r}')")
+          continue
+        fi
+        # cp+mv, not clast_atomic_write: the helper takes content as a
+        # string and would slurp a multi-megabyte session into a bash var.
+        if ! cp "$source" "$tmp" 2>/dev/null; then
+          rm -f "$tmp"
+          error_lines+=("$(jq -cn --arg f "$source" --arg r "copy failed" '{file:$f,reason:$r}')")
+          continue
+        fi
+        if ! mv -f "$tmp" "$dest" 2>/dev/null; then
+          rm -f "$tmp"
+          error_lines+=("$(jq -cn --arg f "$source" --arg r "rename failed" '{file:$f,reason:$r}')")
+          continue
+        fi
+        # Invariant: a manifest line implies the dest file exists. If the
+        # append fails the dest is an orphan; doctor (step 10) will reap
+        # it, and a re-run of snapshot overwrites + retries the append.
+        if ! clast_manifest_append "$session_id" "$source" "$dest_rel" "$mtime_iso" "$source_size" "$day_bucket"; then
+          error_lines+=("$(jq -cn --arg f "$source" --arg r "manifest append failed" '{file:$f,reason:$r}')")
+          continue
+        fi
+      fi
+
+      captured_lines+=("$(jq -cn \
+        --arg sid "$session_id" \
+        --arg src "$source" \
+        --arg snap "$dest_rel" \
+        --argjson b "$source_size" \
+        --arg day "$day_bucket" \
+        '{session_id:$sid, source:$src, snapshot:$snap, bytes:$b, day_bucket:$day}')")
+      captured_segments+=("$segment")
+      total_bytes=$((total_bytes + source_size))
+    done < <(find "$projects_dir" -mindepth 2 -maxdepth 2 -type f -name '*.jsonl' -print0 2>/dev/null | sort -z)
+  fi
+
+  _clast_snapshot_emit_summary "$dry_run" "$skipped" "$total_bytes" \
+    captured_lines error_lines captured_segments
+
+  if (( ${#error_lines[@]} > 0 )); then
+    return 1
+  fi
+  return 0
+}
+
+# _clast_snapshot_emit_summary <dry_run> <skipped> <total_bytes> <caps-arr-name> <errs-arr-name> <segs-arr-name>
+_clast_snapshot_emit_summary() {
+  local dry_run="$1" skipped="$2" total_bytes="$3"
+  local -n _caps="$4"
+  local -n _errs="$5"
+  local -n _segs="$6"
+
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    local caps_json='[]' errs_json='[]'
+    if (( ${#_caps[@]} > 0 )); then
+      caps_json="$(printf '%s\n' "${_caps[@]}" | jq -cs '.')"
+    fi
+    if (( ${#_errs[@]} > 0 )); then
+      errs_json="$(printf '%s\n' "${_errs[@]}" | jq -cs '.')"
+    fi
+    jq -cn --argjson c "$caps_json" --argjson e "$errs_json" --argjson s "$skipped" \
+      '{captured:$c, skipped:$s, errors:$e}'
+    return 0
+  fi
+
+  # Silent no-op: load-bearing for the SessionStart hook (step 11). Re-read
+  # docs/cli-contract.md#clast-snapshot before changing this.
+  if (( ${#_caps[@]} == 0 && ${#_errs[@]} == 0 )); then
+    return 0
+  fi
+
+  if (( dry_run == 1 )); then
+    local i seg sid day
+    for (( i = 0; i < ${#_caps[@]}; i++ )); do
+      seg="${_segs[$i]}"
+      sid="$(jq -r '.session_id' <<<"${_caps[$i]}")"
+      day="$(jq -r '.day_bucket' <<<"${_caps[$i]}")"
+      printf 'would capture: %s/%s → %s\n' "$seg" "$sid" "$day" >&2
+    done
+  elif (( ${#_caps[@]} > 0 )) && [[ -z "${CLAST_QUIET:-}" ]]; then
+    declare -A counts=()
+    local i seg label slug
+    for (( i = 0; i < ${#_caps[@]}; i++ )); do
+      seg="${_segs[$i]}"
+      if slug="$(clast_registry_resolve "$seg" 2>/dev/null)" && [[ -n "$slug" ]]; then
+        label="$slug"
+      else
+        label="$seg"
+      fi
+      counts["$label"]=$(( ${counts["$label"]:-0} + 1 ))
+    done
+
+    local mb
+    mb="$(awk -v b="$total_bytes" 'BEGIN{printf "%.1f", b/1048576}')"
+    printf 'Captured %d session(s) across %d project(s) (%s MB).\n' \
+      "${#_caps[@]}" "${#counts[@]}" "$mb"
+
+    local key cnt
+    while IFS=$'\t' read -r key cnt; do
+      printf '  %s: %s session(s)\n' "$key" "$cnt"
+    done < <(
+      for key in "${!counts[@]}"; do
+        printf '%s\t%s\n' "$key" "${counts[$key]}"
+      done | sort -t$'\t' -k2,2nr -k1,1
+    )
+  fi
+
+  if (( ${#_errs[@]} > 0 )); then
+    printf '%d error(s); see --json for details.\n' "${#_errs[@]}" >&2
+  fi
+}

package/lib/clast/clast-subcommands/stats.bash

@@ -0,0 +1,354 @@
+# clast-subcommands/stats.bash — `clast stats`.
+#
+# Read-only summary of journal activity over a date window using manifest
+# + filesystem stat only. No JSONL body parsing. See
+# docs/cli-contract.md#clast-stats.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+# shellcheck source=lib/clast/clast-manifest-lib.bash
+# shellcheck source=lib/clast/clast-registry-lib.bash
+# shellcheck source=lib/clast/clast-decode-lib.bash
+
+_clast_stats_usage() {
+  cat <<'EOF'
+Usage: clast stats [--day DATE] [--since DATE] [--until DATE] [--project SLUG]
+
+Summarize journal activity over a date window (default: today).
+
+Flags:
+  --day DATE       Single-day window. Mutually exclusive with --since/--until.
+  --since DATE     Start of range (inclusive).
+  --until DATE     End of range (inclusive).
+  --project SLUG   Filter to one registered project slug.
+  -h, --help       Print this usage and exit.
+
+DATE accepts ISO (YYYY-MM-DD), `today`, `yesterday`, `last-week`,
+`-Nd`, or `-Nw`. See docs/cli-contract.md#date-parsing.
+EOF
+}
+
+_clast_stats_err() {
+  local msg="$1" code="${2:-2}"
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    jq -cn --arg m "$msg" --argjson c "$code" '{error:$m, code:$c}'
+  else
+    clast_log_error "stats: $msg"
+  fi
+}
+
+# _clast_stats_human_bytes <int>
+#   Render bytes as "<n> B" / "<x.x> KB" / "<x.x> MB" / "<x.x> GB".
+#   Base-2 math, base-10 labels — matches snapshot summary from step 06.
+_clast_stats_human_bytes() {
+  local b="$1"
+  if (( b < 1024 )); then
+    printf '%s B' "$b"
+    return 0
+  fi
+  awk -v b="$b" 'BEGIN {
+    units[0] = "KB"; units[1] = "MB"; units[2] = "GB"; units[3] = "TB"
+    i = 0
+    v = b / 1024
+    while (v >= 1024 && i < 3) { v = v / 1024; i++ }
+    printf "%.1f %s", v, units[i]
+  }'
+}
+
+clast_cmd_stats() {
+  local day_input="" since_input="" until_input=""
+  local day_filter="" since_date="" until_date=""
+  local project_filter=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --day)
+        if [[ $# -lt 2 ]]; then _clast_stats_err "--day requires a value"; return 2; fi
+        day_input="$2"
+        if ! day_filter="$(clast_parse_date "$2" 2>/dev/null)"; then
+          _clast_stats_err "invalid date '$2'"; return 2
+        fi
+        shift 2 ;;
+      --day=*)
+        day_input="${1#*=}"
+        if ! day_filter="$(clast_parse_date "$day_input" 2>/dev/null)"; then
+          _clast_stats_err "invalid date '$day_input'"; return 2
+        fi
+        shift ;;
+      --since)
+        if [[ $# -lt 2 ]]; then _clast_stats_err "--since requires a value"; return 2; fi
+        since_input="$2"
+        if ! since_date="$(clast_parse_date "$2" 2>/dev/null)"; then
+          _clast_stats_err "invalid date '$2'"; return 2
+        fi
+        shift 2 ;;
+      --since=*)
+        since_input="${1#*=}"
+        if ! since_date="$(clast_parse_date "$since_input" 2>/dev/null)"; then
+          _clast_stats_err "invalid date '$since_input'"; return 2
+        fi
+        shift ;;
+      --until)
+        if [[ $# -lt 2 ]]; then _clast_stats_err "--until requires a value"; return 2; fi
+        until_input="$2"
+        if ! until_date="$(clast_parse_date "$2" 2>/dev/null)"; then
+          _clast_stats_err "invalid date '$2'"; return 2
+        fi
+        shift 2 ;;
+      --until=*)
+        until_input="${1#*=}"
+        if ! until_date="$(clast_parse_date "$until_input" 2>/dev/null)"; then
+          _clast_stats_err "invalid date '$until_input'"; return 2
+        fi
+        shift ;;
+      --project)
+        if [[ $# -lt 2 ]]; then _clast_stats_err "--project requires a value"; return 2; fi
+        project_filter="$2"; shift 2 ;;
+      --project=*)
+        project_filter="${1#*=}"; shift ;;
+      -h|--help)
+        _clast_stats_usage; return 0 ;;
+      --) shift; break ;;
+      -*) _clast_stats_err "unknown flag '$1'"; return 2 ;;
+      *)  _clast_stats_err "unexpected positional '$1'"; return 2 ;;
+    esac
+  done
+
+  if [[ -n "$day_filter" && ( -n "$since_date" || -n "$until_date" ) ]]; then
+    _clast_stats_err "--day cannot be combined with --since or --until"
+    return 2
+  fi
+
+  local today
+  today="$(clast_today)"
+  local label_suffix="" json_label=""
+  local window_start window_end
+  if [[ -n "$day_filter" ]]; then
+    window_start="$day_filter"
+    window_end="$day_filter"
+    if [[ "$day_filter" == "$today" ]]; then
+      label_suffix=" (today)"; json_label="today"
+    else
+      local yest
+      yest="$(clast_parse_date yesterday)"
+      if [[ "$day_filter" == "$yest" ]]; then
+        label_suffix=" (yesterday)"; json_label="yesterday"
+      fi
+    fi
+  elif [[ -z "$since_date" && -z "$until_date" ]]; then
+    window_start="$today"
+    window_end="$today"
+    label_suffix=" (today)"; json_label="today"
+  else
+    if [[ -z "$since_date" ]]; then
+      since_date="1970-01-01"
+    fi
+    local until_was_default=0
+    if [[ -z "$until_date" ]]; then
+      until_date="$today"
+      until_was_default=1
+    fi
+    window_start="$since_date"
+    window_end="$until_date"
+    if (( until_was_default == 1 )); then
+      label_suffix=" (through today)"; json_label="through_today"
+    fi
+  fi
+
+  if ! [[ "$window_start" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+    _clast_stats_err "invalid date '$window_start'"; return 2
+  fi
+  if ! [[ "$window_end" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+    _clast_stats_err "invalid date '$window_end'"; return 2
+  fi
+  if [[ "$window_start" > "$window_end" ]]; then
+    _clast_stats_err "--since must be <= --until"
+    return 2
+  fi
+
+  # Validate --project slug exists in registry.
+  if [[ -n "$project_filter" ]]; then
+    local reg_json slug_match
+    reg_json="$(clast_registry_list_json)"
+    slug_match="$(jq -r --arg s "$project_filter" \
+      'map(select(.slug == $s)) | .[0].slug // empty' <<<"$reg_json")"
+    if [[ -z "$slug_match" ]]; then
+      _clast_stats_err "unknown project slug '$project_filter'" 1
+      return 1
+    fi
+  fi
+
+  if [[ -n "${CLAST_VERBOSE:-}" ]]; then
+    clast_log_info "stats: window $window_start..$window_end"
+  fi
+
+  # Stream manifest rows in window, reduce to most-recent per session_id.
+  local journal_dir
+  journal_dir="$(clast_journal_dir)"
+
+  local filter
+  if [[ "$window_start" == "$window_end" ]]; then
+    filter='.day_bucket == "'"$window_start"'"'
+  else
+    filter='.day_bucket >= "'"$window_start"'" and .day_bucket <= "'"$window_end"'"'
+  fi
+
+  local rows_json='[]'
+  local raw
+  raw="$(clast_manifest_iterate "$filter" | jq -cs \
+    'group_by(.session_id) | map(max_by(.captured_at))')"
+  if [[ -n "$raw" ]]; then
+    rows_json="$raw"
+  fi
+
+  local n
+  n="$(jq 'length' <<<"$rows_json")"
+
+  # Resolve project slug per row, apply --project filter.
+  local -A slug_counts=()
+  local i row source snapshot seg slug bytes_sum=0 msgs_sum=0
+  local n_sessions=0
+  for (( i = 0; i < n; i++ )); do
+    row="$(jq -c ".[$i]" <<<"$rows_json")"
+    source="$(jq -r '.source' <<<"$row")"
+    snapshot="$(jq -r '.snapshot' <<<"$row")"
+    seg="$(awk -F/ 'NR==1{print $3}' <<<"$snapshot")"
+
+    slug=""
+    if [[ "$source" != "null" && -n "$source" ]]; then
+      # Prefer the manifest source (authoritative under path moves) — try
+      # dirname(source) since the registry stores project directories while
+      # source carries the .jsonl filename. Fall back to the snapshot
+      # segment when the source path is not registered.
+      local source_dir
+      source_dir="$(dirname "$source")"
+      if ! slug="$(clast_registry_resolve "$source_dir" 2>/dev/null)" || [[ -z "$slug" ]]; then
+        if ! slug="$(clast_registry_resolve "$seg" 2>/dev/null)" || [[ -z "$slug" ]]; then
+          slug="$seg"
+        fi
+      fi
+    fi
+
+    if [[ -n "$project_filter" ]]; then
+      if [[ "$slug" != "$project_filter" ]]; then
+        continue
+      fi
+    fi
+
+    n_sessions=$((n_sessions + 1))
+    if [[ -n "$slug" ]]; then
+      slug_counts["$slug"]=1
+    fi
+
+    local size
+    size="$(jq -r '.source_size // 0' <<<"$row")"
+    [[ "$size" =~ ^[0-9]+$ ]] || size=0
+    bytes_sum=$((bytes_sum + size))
+
+    local abs="$journal_dir/$snapshot" m=0
+    if [[ -r "$abs" ]]; then
+      m="$(wc -l <"$abs" 2>/dev/null | tr -d ' ')"
+      [[ -z "$m" ]] && m=0
+    fi
+    msgs_sum=$((msgs_sum + m))
+  done
+
+  local n_projects=${#slug_counts[@]}
+
+  # Curated count: entries/*.md files whose date prefix is in window.
+  local curated=0
+  local entries_dir="$journal_dir/entries"
+  if [[ -d "$entries_dir" ]]; then
+    local f base prefix
+    while IFS= read -r f; do
+      [[ -z "$f" ]] && continue
+      base="$(basename "$f")"
+      prefix="${base:0:10}"
+      if [[ "$prefix" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] \
+         && ! [[ "$prefix" < "$window_start" ]] \
+         && ! [[ "$prefix" > "$window_end" ]]; then
+        curated=$((curated + 1))
+      fi
+    done < <(find "$entries_dir" -mindepth 1 -maxdepth 1 -type f -name '*.md' 2>/dev/null)
+  fi
+
+  local curated_pct=0
+  if (( n_sessions > 0 )); then
+    curated_pct=$(( (curated * 100 + n_sessions / 2) / n_sessions ))
+    if (( curated_pct > 100 )); then curated_pct=100; fi
+  fi
+
+  # Breadcrumb count: breadcrumbs/<YYYY-MM-DD>-<slug>.md in window.
+  local breadcrumbs=0
+  local -A breadcrumb_slugs=()
+  local breadcrumbs_dir="$journal_dir/breadcrumbs"
+  if [[ -d "$breadcrumbs_dir" ]]; then
+    local bf bname bprefix brest bslug
+    while IFS= read -r bf; do
+      [[ -z "$bf" ]] && continue
+      bname="$(basename "$bf")"
+      bprefix="${bname:0:10}"
+      if [[ "$bprefix" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] \
+         && ! [[ "$bprefix" < "$window_start" ]] \
+         && ! [[ "$bprefix" > "$window_end" ]]; then
+        breadcrumbs=$((breadcrumbs + 1))
+        brest="${bname:11}"
+        bslug="${brest%.md}"
+        if [[ -n "$bslug" ]]; then
+          breadcrumb_slugs["$bslug"]=1
+        fi
+      fi
+    done < <(find "$breadcrumbs_dir" -mindepth 1 -maxdepth 1 -type f -name '*.md' 2>/dev/null)
+  fi
+  local breadcrumb_projects=${#breadcrumb_slugs[@]}
+
+  local bytes_human
+  bytes_human="$(_clast_stats_human_bytes "$bytes_sum")"
+
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    jq -cn \
+      --arg start "$window_start" \
+      --arg end "$window_end" \
+      --arg label "$json_label" \
+      --argjson projects "$n_projects" \
+      --argjson sessions "$n_sessions" \
+      --argjson messages_approx "$msgs_sum" \
+      --argjson bytes "$bytes_sum" \
+      --arg bytes_human "$bytes_human" \
+      --argjson curated "$curated" \
+      --argjson curated_pct "$curated_pct" \
+      --argjson breadcrumbs "$breadcrumbs" \
+      --argjson breadcrumb_projects "$breadcrumb_projects" \
+      '{
+        window: {start:$start, end:$end, label:$label},
+        projects: $projects,
+        sessions: $sessions,
+        messages_approx: $messages_approx,
+        bytes: $bytes,
+        bytes_human: $bytes_human,
+        curated: $curated,
+        curated_pct: $curated_pct,
+        breadcrumbs: $breadcrumbs,
+        breadcrumb_projects: $breadcrumb_projects
+      }'
+    return 0
+  fi
+
+  if [[ -n "${CLAST_QUIET:-}" ]]; then
+    return 0
+  fi
+
+  local window_text
+  if [[ "$window_start" == "$window_end" ]]; then
+    window_text="$window_start"
+  else
+    window_text="$window_start..$window_end"
+  fi
+
+  printf '%-12s %s%s\n' "Window:"      "$window_text" "$label_suffix"
+  printf '%-12s %d\n'   "Projects:"    "$n_projects"
+  printf '%-12s %d\n'   "Sessions:"    "$n_sessions"
+  printf '%-12s %d (approx)\n' "Messages:" "$msgs_sum"
+  printf '%-12s %s\n'   "Bytes:"       "$bytes_human"
+  printf '%-12s %d of %d sessions (%d%%)\n' "Curated:" "$curated" "$n_sessions" "$curated_pct"
+  printf '%-12s %d across %d projects\n' "Breadcrumbs:" "$breadcrumbs" "$breadcrumb_projects"
+}