@procrastivity/clast 0.0.3 → 0.0.5

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

@@ -147,39 +147,53 @@ _clast_doctor_check_registry_validity() {
     return 0
   fi
 
-  # Duplicate slug + alias collisions, computed across the parseable subset.
+  # Path conflicts + alias collisions, computed across the parseable subset.
   local entries_json='[]'
   if (( ${#entries[@]} > 0 )); then
     entries_json="$(printf '%s\n' "${entries[@]}" | jq -cs .)"
   fi
 
-  local dup_lines
-  dup_lines="$(jq -r '
-    [.[] | .slug] | group_by(.)
-    | map(select(length > 1) | .[0]) | .[]
+  # A shared slug across distinct .path lines is the supported way to span
+  # multiple directories (worktrees / clones) of one logical project — see
+  # data-model.md. So duplicate slugs are NOT a problem. Genuine problems
+  # are keyed on path: the same path registered more than once, or one path
+  # claimed by more than one slug.
+  local path_issues
+  path_issues="$(jq -r '
+    group_by(.path)
+    | map(select(length > 1))
+    | .[]
+    | ([ .[].slug ] | unique) as $slugs
+    | if ($slugs | length) > 1
+      then "path conflict: " + .[0].path + " maps to slugs " + ($slugs | join(", "))
+      else "duplicate path: " + .[0].path
+      end
   ' <<<"$entries_json")"
-  local dup_slug
-  while IFS= read -r dup_slug; do
-    [[ -z "$dup_slug" ]] && continue
-    issues+=("duplicate slug: $dup_slug")
-  done <<<"$dup_lines"
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    issues+=("$line")
+  done <<<"$path_issues"
 
+  # Alias collisions only matter across *different* slugs: two lines of one
+  # slug sharing an alias (or a legacy roll-up) is benign.
   local collisions
   collisions="$(jq -r '
     . as $arr
     | [
-        # alias collides with another entry'"'"'s slug
+        # alias collides with a *different* entry'"'"'s slug
         ( range(0; length) as $i
           | range(0; length) as $j
           | select($i != $j)
+          | select($arr[$i].slug != $arr[$j].slug)
           | ($arr[$i].aliases // []) as $aliases
           | select($aliases | index($arr[$j].slug) != null)
           | "alias collision: " + $arr[$i].slug + " aliases slug " + $arr[$j].slug
         ),
-        # alias collides with another entry'"'"'s alias (shared alias across two slugs)
+        # two *different* slugs share an alias path
         ( range(0; length) as $i
           | range(0; length) as $j
           | select($i < $j)
+          | select($arr[$i].slug != $arr[$j].slug)
           | ($arr[$i].aliases // []) as $ai
           | ($arr[$j].aliases // []) as $aj
           | ($ai | map(select(. as $x | $aj | index($x) != null))) as $shared
@@ -201,8 +215,10 @@ _clast_doctor_check_registry_validity() {
       "${issues[@]}"
     return 0
   fi
+  local proj_count
+  proj_count="$(jq -r '[.[].slug] | unique | length' <<<"$entries_json")"
   _clast_doctor_emit "registry_validity" "ok" \
-    "$valid_count projects, no duplicates"
+    "$valid_count line(s), $proj_count project(s), no conflicts"
 }
 
 # Compute the deduped (most-recent per session_id) manifest rows.

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

@@ -69,49 +69,23 @@ clast_cmd_entries() {
 
 # _clast_entries_read_frontmatter <path>
 #   Emit raw frontmatter lines (between the first two `---` fences) to stdout.
+#   Thin alias over the shared primitive in clast-lib.bash.
 _clast_entries_read_frontmatter() {
-  local path="$1"
-  awk '
-    BEGIN { in_fm = 0; seen = 0 }
-    /^---[[:space:]]*$/ {
-      if (!seen) { in_fm = 1; seen = 1; next }
-      if (in_fm) { exit }
-    }
-    in_fm { print }
-  ' "$path"
+  clast_read_frontmatter "$1"
 }
 
 # _clast_entries_extract_title <path>
 #   Look for `# Session: <title>` as the first non-blank body line.
+#   Thin alias over the shared primitive in clast-lib.bash.
 _clast_entries_extract_title() {
-  awk '
-    BEGIN { in_fm = 0; seen = 0; past = 0 }
-    /^---[[:space:]]*$/ {
-      if (!seen) { in_fm = 1; seen = 1; next }
-      if (in_fm) { in_fm = 0; past = 1; next }
-    }
-    in_fm { next }
-    past {
-      if ($0 ~ /^[[:space:]]*$/) next
-      if (sub(/^# Session: /, "")) { print; exit }
-      exit
-    }
-  ' "$1"
+  clast_entry_title "$1"
 }
 
 # _clast_entries_unquote <string>
 #   Strip surrounding double quotes and unescape \", \\, \n.
+#   Thin alias over the shared primitive in clast-lib.bash.
 _clast_entries_unquote() {
-  local v="$1"
-  if [[ "${v:0:1}" == '"' && "${v: -1}" == '"' && ${#v} -ge 2 ]]; then
-    v="${v:1:${#v}-2}"
-    # Process escapes in order: \\ → placeholder, \" → ", \n → LF, placeholder → \
-    v="${v//\\\\/$'\x01'}"
-    v="${v//\\\"/\"}"
-    v="${v//\\n/$'\n'}"
-    v="${v//$'\x01'/\\}"
-  fi
-  printf '%s' "$v"
+  clast_yaml_unquote "$1"
 }
 
 # ---------------------------------------------------------------------------
@@ -290,7 +264,7 @@ _clast_entries_list_consider() {
   fi
 
   # Parse frontmatter.
-  local fm_date="" fm_time="" fm_day_bucket="" fm_project=""
+  local fm_date="" fm_time="" fm_day_bucket="" fm_project="" fm_label=""
   local fm_session_id="" fm_session_slug="" fm_branch=""
   local fm_tags_raw=""
   local line key val
@@ -307,6 +281,11 @@ _clast_entries_list_consider() {
       time)         fm_time="$(_clast_entries_unquote "$val")" ;;
       day_bucket)   fm_day_bucket="$(_clast_entries_unquote "$val")" ;;
       project)      fm_project="$(_clast_entries_unquote "$val")" ;;
+      label)
+        if [[ "$val" != "null" ]]; then
+          fm_label="$(_clast_entries_unquote "$val")"
+        fi
+        ;;
       session_id)   fm_session_id="$(_clast_entries_unquote "$val")" ;;
       session_slug) fm_session_slug="$(_clast_entries_unquote "$val")" ;;
       branch)
@@ -372,6 +351,7 @@ _clast_entries_list_consider() {
     --arg time "$fm_time" \
     --arg day_bucket "$bucket" \
     --arg project "$fm_project" \
+    --arg label "$fm_label" \
     --arg session_id "$fm_session_id" \
     --arg session_slug "$fm_session_slug" \
     --arg branch "$fm_branch" \
@@ -383,6 +363,7 @@ _clast_entries_list_consider() {
        time: $time,
        day_bucket: $day_bucket,
        project: $project,
+       label: (if $label == "" then null else $label end),
        session_id: $session_id,
        session_slug: $session_slug,
        branch: (if $branch == "" then null else $branch end),
@@ -512,9 +493,16 @@ _clast_entries_write() {
       trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
       [[ -z "$trimmed" ]] && continue
       trimmed="${trimmed,,}"
-      if ! [[ "$trimmed" =~ ^[a-z0-9][a-z0-9-]{0,31}$ ]]; then
-        _clast_entries_err "write: invalid tag '$trimmed'"; return 2
-      fi
+      # Normalize to the tag charset rather than rejecting. LLM-suggested tags
+      # routinely carry dots or other separators (e.g. "php-8.5"), and failing
+      # the whole write would discard a curated entry over a cosmetic tag. Map
+      # runs of disallowed characters to a single hyphen, trim edge hyphens,
+      # and cap at 32 chars — same shape as _clast_wake_slugify. A tag that
+      # normalizes to nothing (all punctuation) is dropped.
+      trimmed="$(printf '%s' "$trimmed" | sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//')"
+      trimmed="${trimmed:0:32}"
+      trimmed="${trimmed%-}"
+      [[ -z "$trimmed" ]] && continue
       tags+=("$trimmed")
     done
   fi
@@ -534,20 +522,17 @@ _clast_entries_write() {
   local seg
   seg="$(awk -F/ 'NR==1{print $3}' <<<"$snapshot_rel")"
 
-  # Resolve project from registry.
-  local project_slug="" project_path="" project_remote=""
-  local resolved_slug=""
-  if resolved_slug="$(clast_registry_resolve "$seg" 2>/dev/null)" && [[ -n "$resolved_slug" ]]; then
-    local reg_json reg_match
-    reg_json="$(clast_registry_list_json)"
-    reg_match="$(jq -c --arg s "$resolved_slug" 'map(select(.slug == $s)) | .[0] // empty' <<<"$reg_json")"
-    if [[ -n "$reg_match" ]]; then
-      project_slug="$resolved_slug"
-      project_path="$(jq -r '.path // empty' <<<"$reg_match")"
-      project_remote="$(jq -r '.remote // empty' <<<"$reg_match")"
-    else
-      project_slug="$resolved_slug"
-    fi
+  # Resolve the *specific* registry line for this session's directory (by
+  # path), not the first line that shares the slug. A slug may span several
+  # directories (clones/worktrees), each with its own path and label;
+  # slug-first-match would stamp every entry with the first line's path.
+  local project_slug="" project_path="" project_remote="" project_label=""
+  local reg_line=""
+  if reg_line="$(clast_registry_line_for_path "$seg" 2>/dev/null)" && [[ -n "$reg_line" ]]; then
+    project_slug="$(jq -r '.slug // empty' <<<"$reg_line")"
+    project_path="$(jq -r '.path // empty' <<<"$reg_line")"
+    project_remote="$(jq -r '.remote // empty' <<<"$reg_line")"
+    project_label="$(jq -r '.label // empty' <<<"$reg_line")"
   else
     project_slug="$seg"
     local -a decoded=()
@@ -619,6 +604,11 @@ _clast_entries_write() {
   else
     fm+="project_path: null"$'\n'
   fi
+  if [[ -n "$project_label" ]]; then
+    fm+="label: $(_clast_entries_yaml_string "$project_label")"$'\n'
+  else
+    fm+="label: null"$'\n'
+  fi
   if [[ -n "$project_remote" ]]; then
     fm+="project_remote: $(_clast_entries_yaml_string "$project_remote")"$'\n'
   else

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

@@ -145,8 +145,14 @@ clast_cmd_projects() {
 
     seg_session_count["$seg"]=$(( ${seg_session_count["$seg"]:-0} + 1 ))
 
+    # Prefer cached msg_count on the manifest line (step 21); fall back to
+    # counting transcript lines for legacy lines that predate the cache.
     abs_path="$journal_dir/$snapshot"
-    if [[ -r "$abs_path" ]]; then
+    local cached_msgs
+    cached_msgs="$(jq -r '.msg_count // empty' <<<"$line")"
+    if [[ -n "$cached_msgs" ]]; then
+      msgs="$cached_msgs"
+    elif [[ -r "$abs_path" ]]; then
       msgs="$(wc -l <"$abs_path" 2>/dev/null | tr -d ' ')"
       [[ -z "$msgs" ]] && msgs=0
     else
@@ -163,13 +169,18 @@ clast_cmd_projects() {
   done
 
   # Build per-segment rows as JSON, applying registry + --unregistered.
+  # Resolve each segment to its OWN registry line (not slug-first-match) so
+  # that a project spanning multiple checkouts under one shared slug reports
+  # each segment's own path/remote, instead of collapsing every row onto the
+  # first checkout's path.
   local -a rows=()
-  local slug path remote registered row decode_rc decoded
+  local slug path remote registered row decode_rc decoded line
   for seg in "${!seg_session_count[@]}"; do
-    if slug="$(clast_registry_resolve "$seg" 2>/dev/null)" && [[ -n "$slug" ]]; then
+    if line="$(clast_registry_line_for_path "$seg" 2>/dev/null)" && [[ -n "$line" ]]; then
       registered=true
-      path="$(_clast_projects_path_for_slug "$slug")"
-      remote="$(_clast_projects_remote_for_slug "$slug")"
+      slug="$(jq -r '.slug // empty' <<<"$line")"
+      path="$(jq -r '.path // empty' <<<"$line")"
+      remote="$(jq -r '.remote // empty' <<<"$line")"
     else
       registered=false
       slug=""
@@ -292,18 +303,3 @@ _clast_projects_window_filter() {
   printf '%s' "$joined"
 }
 
-# _clast_projects_path_for_slug <slug>
-#   First registry path for <slug>, or empty.
-_clast_projects_path_for_slug() {
-  local slug="$1"
-  clast_registry_list_json \
-    | jq -r --arg s "$slug" 'map(select(.slug == $s)) | .[0].path // empty'
-}
-
-# _clast_projects_remote_for_slug <slug>
-#   First non-empty registry remote for <slug>, or empty.
-_clast_projects_remote_for_slug() {
-  local slug="$1"
-  clast_registry_list_json \
-    | jq -r --arg s "$slug" 'map(select(.slug == $s and (.remote // "") != "")) | .[0].remote // empty'
-}

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

@@ -63,15 +63,16 @@ EOF
     return 0
   fi
 
-  printf '%-17s %-33s %-43s %s\n' slug path remote aliases
-  local n i slug path remote aliases
+  printf '%-17s %-13s %-33s %-43s %s\n' slug label path remote aliases
+  local n i slug label path remote aliases
   n="$(jq 'length' <<<"$arr")"
   for (( i = 0; i < n; i++ )); do
     slug="$(jq -r ".[$i].slug // \"\"" <<<"$arr")"
+    label="$(jq -r ".[$i].label // \"\" | if . == \"\" then \"(none)\" else . end" <<<"$arr")"
     path="$(jq -r ".[$i].path // \"\"" <<<"$arr")"
     remote="$(jq -r ".[$i].remote // \"\"" <<<"$arr")"
     aliases="$(jq -r ".[$i].aliases // [] | if length == 0 then \"(none)\" else join(\",\") end" <<<"$arr")"
-    printf '%-17s %-33s %-43s %s\n' "$slug" "$path" "$remote" "$aliases"
+    printf '%-17s %-13s %-33s %-43s %s\n' "$slug" "$label" "$path" "$remote" "$aliases"
   done
 }
 
@@ -83,18 +84,18 @@ _clast_registry_op_add() {
       --json) json=1; shift ;;
       -h|--help)
         cat <<'EOF'
-Usage: clast registry add <path> [--slug NAME] [--remote URL] [--json]
+Usage: clast registry add <path> [--slug NAME] [--label NAME] [--remote URL] [--json]
 EOF
         return 0
         ;;
       # TODO(v1.1): interactive --slug prompt when stdin is a TTY.
-      --slug|--remote)
+      --slug|--label|--remote)
         if [[ $# -lt 2 ]]; then
           clast_log_error "registry add: $1 requires a value"
           return 2
         fi
         passthrough+=("$1" "$2"); shift 2 ;;
-      --slug=*|--remote=*)
+      --slug=*|--label=*|--remote=*)
         passthrough+=("$1"); shift ;;
       *)
         passthrough+=("$1"); shift ;;
@@ -110,10 +111,15 @@ EOF
   if [[ -n "$json" ]]; then
     printf '%s\n' "$line"
   else
-    local slug path
+    local slug label path
     slug="$(jq -r '.slug' <<<"$line")"
+    label="$(jq -r '.label // ""' <<<"$line")"
     path="$(jq -r '.path' <<<"$line")"
-    printf 'registered %s → %s\n' "$slug" "$path"
+    if [[ -n "$label" ]]; then
+      printf 'registered %s (%s) → %s\n' "$slug" "$label" "$path"
+    else
+      printf 'registered %s → %s\n' "$slug" "$path"
+    fi
   fi
 }
 
@@ -126,6 +132,9 @@ _clast_registry_op_resolve() {
       -h|--help)
         cat <<'EOF'
 Usage: clast registry resolve <path-or-segment> [--json]
+
+Prints the resolved slug. With --json, also includes the directory's
+`label` when the matched line has one.
 EOF
         return 0
         ;;
@@ -144,10 +153,16 @@ EOF
     return 2
   fi
 
-  local slug
-  if slug="$(clast_registry_resolve "$input")" && [[ -n "$slug" ]]; then
+  # Resolve to the specific line so --json can surface the per-directory
+  # label (not just the slug). Human output stays slug-only.
+  local line
+  if line="$(clast_registry_line_for_path "$input")" && [[ -n "$line" ]]; then
+    local slug label
+    slug="$(jq -r '.slug // empty' <<<"$line")"
+    label="$(jq -r '.label // empty' <<<"$line")"
     if [[ -n "$json" ]]; then
-      jq -cn --arg slug "$slug" '{slug: $slug}'
+      jq -cn --arg slug "$slug" --arg label "$label" \
+        '{slug: $slug} + (if $label == "" then {} else {label: $label} end)'
     else
       printf '%s\n' "$slug"
     fi

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

@@ -0,0 +1,217 @@
+# clast-subcommands/retro.bash — `clast-plumbing retro`.
+#
+# Round 1 of the retro feature: run the deterministic day→project manifest
+# (clast_retro_manifest) and render it from the raw entry bodies, in work-day
+# order. No LLM. `--json` emits the manifest verbatim; the human render is the
+# deterministic retro document the porcelain `clast retro` will later condense.
+# See .wip/initiatives/clast-retro/.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+# shellcheck source=lib/clast/clast-retro-lib.bash
+source "$CLAST_LIB/clast-retro-lib.bash"
+
+_clast_retro_usage() {
+  cat <<'EOF'
+Usage: clast retro [--from DATE] [--to DATE] [--window work-days|file-dates]
+
+Summarize work grouped by the day it actually happened → project, from the
+curated journal entries. Deterministic; no model call.
+
+Flags:
+  --from DATE     Start of the window (inclusive). Default: corpus start.
+  --to DATE       End of the window (inclusive). Default: corpus end.
+  --window WHICH  work-days (default): keep sessions whose work day is in range.
+                  file-dates: keep entries whose filename date is in range
+                  (pulls earlier work days reachable from those files).
+  --bodies        With --json only: add each session's merged entry `body`.
+  -h, --help      Print this usage and exit.
+
+DATE accepts ISO (YYYY-MM-DD), `today`, `yesterday`, `last-week`, `-Nd`, `-Nw`.
+With --json, emits the raw day→project manifest instead of the rendered report.
+EOF
+}
+
+_clast_retro_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 "retro: $msg"
+  fi
+}
+
+clast_cmd_retro() {
+  local from="" to="" window="work-days" bodies=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --bodies) bodies=1; shift ;;
+      --from)
+        if [[ $# -lt 2 ]]; then _clast_retro_err "--from requires a value"; return 2; fi
+        if ! from="$(clast_parse_date "$2" 2>/dev/null)"; then
+          _clast_retro_err "invalid date '$2'"; return 2
+        fi
+        shift 2 ;;
+      --from=*)
+        if ! from="$(clast_parse_date "${1#*=}" 2>/dev/null)"; then
+          _clast_retro_err "invalid date '${1#*=}'"; return 2
+        fi
+        shift ;;
+      --to)
+        if [[ $# -lt 2 ]]; then _clast_retro_err "--to requires a value"; return 2; fi
+        if ! to="$(clast_parse_date "$2" 2>/dev/null)"; then
+          _clast_retro_err "invalid date '$2'"; return 2
+        fi
+        shift 2 ;;
+      --to=*)
+        if ! to="$(clast_parse_date "${1#*=}" 2>/dev/null)"; then
+          _clast_retro_err "invalid date '${1#*=}'"; return 2
+        fi
+        shift ;;
+      --window)
+        if [[ $# -lt 2 ]]; then _clast_retro_err "--window requires a value"; return 2; fi
+        window="$2"; shift 2 ;;
+      --window=*) window="${1#*=}"; shift ;;
+      -h|--help) _clast_retro_usage; return 0 ;;
+      --) shift; break ;;
+      -*) _clast_retro_err "unknown flag '$1'"; return 2 ;;
+      *)  _clast_retro_err "unexpected positional '$1'"; return 2 ;;
+    esac
+  done
+
+  case "$window" in
+    work-days|file-dates) ;;
+    *) _clast_retro_err "--window must be 'work-days' or 'file-dates'"; return 2 ;;
+  esac
+
+  if [[ -n "$from" && -n "$to" && "$from" > "$to" ]]; then
+    _clast_retro_err "--from must be <= --to"; return 2
+  fi
+
+  local manifest
+  manifest="$(clast_retro_manifest \
+    ${from:+--from "$from"} ${to:+--to "$to"} --window "$window")" || return $?
+
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    if (( bodies )); then
+      manifest="$(_clast_retro_inject_bodies "$manifest")"
+    fi
+    printf '%s\n' "$manifest"
+    return 0
+  fi
+  if (( bodies )); then
+    _clast_retro_err "--bodies is only meaningful with --json"; return 2
+  fi
+  if [[ -n "${CLAST_QUIET:-}" ]]; then
+    return 0
+  fi
+
+  _clast_retro_render "$manifest"
+}
+
+# _clast_retro_inject_bodies <manifest-json>
+#   Add a `body` string (the merged trimmed entry bodies) to every session,
+#   for `--json --bodies`. Reuses clast_retro_session_body so the body matches
+#   the human render byte-for-byte.
+_clast_retro_inject_bodies() {
+  local manifest="$1"
+  local -a pairs=()
+  local sess key body entry0 title interrupted
+  while IFS= read -r sess; do
+    [[ -z "$sess" ]] && continue
+    # Key by session_id, falling back to the first entry path when a
+    # legacy/hand-curated session has no id (JSON null): entries[0] is unique
+    # per session, so id-less sessions don't collide on a shared "null" key.
+    key="$(jq -r '.session_id // .entries[0]' <<<"$sess")"
+    body="$(clast_retro_session_body "$sess")"
+    entry0="$(jq -r '.entries[0]' <<<"$sess")"
+    title=""
+    [[ -r "$entry0" ]] && title="$(clast_entry_title "$entry0")"
+    if printf '%s' "$body" | clast_retro_is_interrupted; then
+      interrupted=true
+    else
+      interrupted=false
+    fi
+    # Body via --rawfile (process substitution), never argv: a single merged
+    # body can exceed MAX_ARG_STRLEN (~128 KiB) and silently fail the exec.
+    pairs+=("$(jq -cn --arg k "$key" --rawfile b <(printf '%s' "$body") \
+      --arg t "$title" --argjson i "$interrupted" \
+      '{key:$k, body:$b, title:$t, interrupted:$i}')")
+  done < <(jq -c '.days[].projects[].sessions[]' <<<"$manifest")
+
+  if (( ${#pairs[@]} == 0 )); then
+    printf '%s' "$manifest"
+    return 0
+  fi
+
+  # Manifest on stdin and the body-bearing pairs via --slurpfile — both can be
+  # large, so neither goes through argv. The `session_id // .entries[0]` key is
+  # always a non-null string, so this can't `$x[null]` abort jq ("Cannot index
+  # object with null") and id-less sessions don't collide on a shared key.
+  printf '%s' "$manifest" | jq -c --slurpfile pairs <(printf '%s\n' "${pairs[@]}") '
+    (reduce $pairs[] as $p ({}; .[$p.key] = $p)) as $x
+    | .days |= map(.projects |= map(.sessions |= map(
+        (.session_id // .entries[0]) as $k
+        | . + {body:        ($x[$k].body // null),
+               title:       ($x[$k].title // null),
+               interrupted: ($x[$k].interrupted // false)} )))
+  '
+}
+
+# _clast_retro_render <manifest-json>
+#   Render the day→project report to stdout.
+_clast_retro_render() {
+  local manifest="$1"
+  local from to window
+  from="$(jq -r '.from // "(start)"' <<<"$manifest")"
+  to="$(jq -r '.to // "(end)"' <<<"$manifest")"
+  window="$(jq -r '.window' <<<"$manifest")"
+  printf 'Retro: %s -> %s (%s)\n' "$from" "$to" "$window"
+
+  local nd
+  nd="$(jq '.days | length' <<<"$manifest")"
+  if (( nd == 0 )); then
+    printf '\n(no sessions in range)\n'
+    return 0
+  fi
+
+  local di pj si
+  local day np project ns sess sid shortsid title entry note body flag
+  for (( di = 0; di < nd; di++ )); do
+    day="$(jq -r ".days[$di].day" <<<"$manifest")"
+    printf '\n== %s ==\n' "$day"
+    note="$(_clast_retro_provenance_note "$day" "$(jq -c ".days[$di].curation_dates // []" <<<"$manifest")")"
+    [[ -n "$note" ]] && printf '%s\n' "$note"
+    np="$(jq ".days[$di].projects | length" <<<"$manifest")"
+    for (( pj = 0; pj < np; pj++ )); do
+      project="$(jq -r ".days[$di].projects[$pj].project_name // .days[$di].projects[$pj].project_path // \"(no project)\"" <<<"$manifest")"
+      printf '\n[%s]\n' "$project"
+      ns="$(jq ".days[$di].projects[$pj].sessions | length" <<<"$manifest")"
+      for (( si = 0; si < ns; si++ )); do
+        sess="$(jq -c ".days[$di].projects[$pj].sessions[$si]" <<<"$manifest")"
+        sid="$(jq -r '.session_id' <<<"$sess")"
+        shortsid="${sid:0:8}"
+        entry="$(jq -r '.entries[0]' <<<"$sess")"
+        title=""
+        [[ -r "$entry" ]] && title="$(clast_entry_title "$entry")"
+        [[ -z "$title" ]] && title="(untitled)"
+        body="$(clast_retro_session_body "$sess")"
+        flag=""
+        printf '%s' "$body" | clast_retro_is_interrupted && flag="  [interrupted]"
+        printf '\n  * %s  (%s)%s\n' "$title" "$shortsid" "$flag"
+        printf '%s\n' "$body"
+      done
+    done
+  done
+}
+
+# _clast_retro_provenance_note <work-day> <curation_dates-json>
+#   One-line note when a day's entries were curated on other date(s) than the
+#   work day. Empty when they match (or there's nothing to say).
+_clast_retro_provenance_note() {
+  local day="$1" cd_json="$2"
+  jq -r --arg d "$day" '
+    if . == [] or . == [$d] then empty
+    else "  (filed " + (join(", ")) + "; work day reconstructed from session snapshots)"
+    end' <<<"$cd_json"
+}