@procrastivity/clast 0.0.1 → 0.0.2

package/bin/clast-wake

@@ -0,0 +1,579 @@
+#!/usr/bin/env bash
+# clast-wake — LLM-powered day curation without Claude Code.
+#
+# Replicates the /day-wakeup plugin skill using an OpenAI-compatible
+# chat completions endpoint. Calls clast commands for data, assembles
+# prompts, calls the LLM via curl, presents drafts interactively.
+#
+# Required env vars:
+#   CLAST_LLM_BASE_URL  — e.g. https://api.openai.com/v1
+#   CLAST_LLM_API_KEY   — bearer token
+#   CLAST_LLM_MODEL     — e.g. gpt-4o, llama3
+set -euo pipefail
+
+CLAST_WAKE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+die() { printf 'clast-wake: %s\n' "$1" >&2; exit "${2:-1}"; }
+warn() { printf 'clast-wake: warning: %s\n' "$1" >&2; }
+info() { printf '%s\n' "$1"; }
+
+slugify() {
+  local s="$1"
+  s="${s,,}"
+  s="$(printf '%s' "$s" | sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//')"
+  printf '%s' "${s:0:60}"
+}
+
+separator() {
+  local label="$1"
+  local width=72
+  local pad=$(( width - ${#label} - 4 ))
+  (( pad < 2 )) && pad=2
+  local dashes=""
+  local j
+  for (( j = 0; j < pad; j++ )); do dashes+="─"; done
+  printf '── %s %s\n' "$label" "$dashes"
+}
+
+# ── Preflight ────────────────────────────────────────────────────────
+
+preflight() {
+  if [[ ! -t 0 ]]; then
+    die "clast-wake requires an interactive terminal (stdin is not a tty)."
+  fi
+
+  for tool in clast curl jq; do
+    if ! command -v "$tool" >/dev/null 2>&1; then
+      die "required tool not found: $tool"
+    fi
+  done
+
+  local missing=0
+  if [[ -z "${CLAST_LLM_BASE_URL:-}" ]]; then
+    warn "CLAST_LLM_BASE_URL not set"; missing=1
+  fi
+  if [[ -z "${CLAST_LLM_API_KEY:-}" ]]; then
+    warn "CLAST_LLM_API_KEY not set"; missing=1
+  fi
+  if [[ -z "${CLAST_LLM_MODEL:-}" ]]; then
+    warn "CLAST_LLM_MODEL not set"; missing=1
+  fi
+
+  if (( missing )); then
+    cat >&2 <<'EOF'
+
+Set these env vars before running clast-wake:
+
+  export CLAST_LLM_BASE_URL="https://api.openai.com/v1"
+  export CLAST_LLM_API_KEY="sk-..."
+  export CLAST_LLM_MODEL="gpt-4o"
+
+Or for a local model (ollama, vllm, etc.):
+
+  export CLAST_LLM_BASE_URL="http://localhost:11434/v1"
+  export CLAST_LLM_API_KEY="unused"
+  export CLAST_LLM_MODEL="llama3"
+EOF
+    exit 1
+  fi
+}
+
+# ── LLM call ─────────────────────────────────────────────────────────
+
+llm_chat() {
+  local system_msg="$1"
+  local user_msg="$2"
+
+  local payload
+  payload="$(jq -cn \
+    --arg model "$CLAST_LLM_MODEL" \
+    --arg system "$system_msg" \
+    --arg user "$user_msg" \
+    '{
+      model: $model,
+      messages: [
+        {role: "system", content: $system},
+        {role: "user", content: $user}
+      ],
+      temperature: 0.3
+    }')"
+
+  local response http_code body
+  response="$(curl -s -w '\n%{http_code}' \
+    "${CLAST_LLM_BASE_URL}/chat/completions" \
+    -H "Authorization: Bearer $CLAST_LLM_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$payload" 2>&1)" || true
+
+  http_code="$(tail -n1 <<<"$response")"
+  body="$(sed '$d' <<<"$response")"
+
+  if [[ "$http_code" != "200" ]]; then
+    warn "LLM API returned HTTP $http_code"
+    if [[ -n "$body" ]]; then
+      local err_msg
+      err_msg="$(jq -r '.error.message // .error // .' <<<"$body" 2>/dev/null || echo "$body")"
+      warn "$err_msg"
+    fi
+    return 1
+  fi
+
+  local content
+  content="$(jq -r '.choices[0].message.content // empty' <<<"$body" 2>/dev/null)" || {
+    warn "failed to parse LLM response"
+    return 1
+  }
+
+  if [[ -z "$content" ]]; then
+    warn "LLM returned empty content"
+    return 1
+  fi
+
+  printf '%s' "$content"
+}
+
+# ── Prompt template ──────────────────────────────────────────────────
+
+resolve_prompt_dir() {
+  local dir="$CLAST_WAKE_DIR/lib/clast/prompts"
+  if [[ -d "$dir" ]]; then
+    printf '%s' "$dir"
+    return
+  fi
+  local installed
+  for installed in /usr/local/lib/clast/prompts "$HOME/.local/lib/clast/prompts"; do
+    if [[ -d "$installed" ]]; then
+      printf '%s' "$installed"
+      return
+    fi
+  done
+  die "cannot find prompts directory (checked $dir and install paths)"
+}
+
+load_system_prompt() {
+  local prompt_dir
+  prompt_dir="$(resolve_prompt_dir)"
+  local file="$prompt_dir/day-wakeup-draft-system.md"
+  if [[ ! -r "$file" ]]; then
+    die "system prompt not found: $file"
+  fi
+  cat "$file"
+}
+
+build_user_prompt() {
+  local project="$1" branch="$2" start="$3" end="$4" msg_count="$5"
+  local first_turns="$6" last_turns="$7" breadcrumbs="$8"
+
+  local prompt_dir
+  prompt_dir="$(resolve_prompt_dir)"
+  local template_file="$prompt_dir/day-wakeup-draft-user.md"
+
+  if [[ -r "$template_file" ]]; then
+    local template
+    template="$(cat "$template_file")"
+    template="${template//\{\{project\}\}/${project}}"
+    template="${template//\{\{branch\}\}/${branch:-unknown}}"
+    template="${template//\{\{start\}\}/${start}}"
+    template="${template//\{\{end\}\}/${end}}"
+    template="${template//\{\{msg_count\}\}/${msg_count}}"
+    template="${template//\{\{first_turns\}\}/${first_turns}}"
+    template="${template//\{\{last_turns\}\}/${last_turns}}"
+    template="${template//\{\{breadcrumbs\}\}/${breadcrumbs:-None.}}"
+    printf '%s' "$template"
+  else
+    warn "user prompt template not found: $template_file — using inline fallback"
+    cat <<EOF
+Session metadata:
+- Project: ${project}
+- Branch: ${branch:-unknown}
+- Start: ${start}
+- End: ${end}
+- Approximate messages: ${msg_count}
+
+First turns of the session:
+${first_turns}
+
+Last turns of the session:
+${last_turns}
+
+Breadcrumbs the user left during this session's day:
+${breadcrumbs:-None.}
+EOF
+  fi
+}
+
+# ── Draft parsing ────────────────────────────────────────────────────
+
+extract_title() {
+  local draft="$1"
+  local title
+  title="$(grep -m1 '^# Session:' <<<"$draft" | sed 's/^# Session:[[:space:]]*//')"
+  printf '%s' "$title"
+}
+
+extract_tags() {
+  local draft="$1"
+  local tags
+  tags="$(grep -i '^Suggested tags:' <<<"$draft" | sed 's/^[Ss]uggested tags:[[:space:]]*//')"
+  tags="$(printf '%s' "$tags" | sed 's/[[:space:]]*,[[:space:]]*/,/g')"
+  printf '%s' "$tags"
+}
+
+strip_tags_trailer() {
+  local draft="$1"
+  printf '%s' "$draft" | sed '/^$/{ N; /\n[Ss]uggested tags:/d; }' | sed '/^[Ss]uggested tags:/d'
+}
+
+# ── Session slug ─────────────────────────────────────────────────────
+
+get_session_slug() {
+  local snapshot_path="$1" draft_title="$2"
+  local journal_dir
+  journal_dir="$(clast whereami 2>/dev/null | grep '^journal_dir:' | awk '{print $2}')" || true
+  if [[ -z "$journal_dir" ]]; then
+    journal_dir="${HOME}/.claude/journal"
+  fi
+
+  local abs_path="$journal_dir/$snapshot_path"
+
+  if [[ -r "$abs_path" ]]; then
+    local ai_title
+    ai_title="$(jq -r 'select(.type == "ai-title") | .aiTitle' "$abs_path" 2>/dev/null | tail -1)" || true
+    if [[ -n "$ai_title" && "$ai_title" != "null" ]]; then
+      slugify "$ai_title"
+      return
+    fi
+  fi
+
+  if [[ -n "$draft_title" ]]; then
+    slugify "$draft_title"
+    return
+  fi
+
+  printf 'session'
+}
+
+# ── Interactive menu ─────────────────────────────────────────────────
+
+prompt_choice() {
+  local choice
+  printf '\n  [a] Accept    [e] Edit    [d] Dismiss    [s] Skip    [q] Stop here\n' >/dev/tty
+  printf '  Choice: ' >/dev/tty
+  read -r -n1 choice </dev/tty
+  printf '\n' >/dev/tty
+  printf '%s' "$choice"
+}
+
+prompt_edit_feedback() {
+  local feedback
+  printf '\n  What should change? ' >/dev/tty
+  read -r feedback </dev/tty
+  printf '%s' "$feedback"
+}
+
+# ── Triage ───────────────────────────────────────────────────────────
+
+_clast_wake_triage() {
+  local uncurated="$1" total="$2" day_count="$3"
+  local first_day="$4" last_day="$5" project_count="$6"
+
+  info "Found $total uncurated session(s) across $day_count day(s) ($first_day to $last_day)." >/dev/tty
+  printf '\n' >/dev/tty
+
+  # Show per-day breakdown
+  local breakdown
+  breakdown="$(jq -r '
+    group_by(.day_bucket) | sort_by(.[0].day_bucket) | .[] |
+    "    \(.[0].day_bucket)  \(length) session(s)"
+  ' <<<"$uncurated")"
+  printf '%s\n' "$breakdown" >/dev/tty
+  printf '\n' >/dev/tty
+
+  local choice
+  printf '  [a] Process all %s sessions\n' "$total" >/dev/tty
+  printf '  [y] Process yesterday only\n' >/dev/tty
+  printf '  [n] Choose how many days back\n' >/dev/tty
+  printf '  [o] Dismiss everything older, then process the rest\n' >/dev/tty
+  printf '  [q] Quit\n' >/dev/tty
+  printf '  Choice: ' >/dev/tty
+  read -r -n1 choice </dev/tty
+  printf '\n' >/dev/tty
+
+  case "$choice" in
+    a|A)
+      printf '%s' "$uncurated"
+      ;;
+    y|Y)
+      local yesterday
+      yesterday="$(date -d 'yesterday' +%Y-%m-%d)"
+      jq -c "[.[] | select(.day_bucket == \"$yesterday\")]" <<<"$uncurated"
+      ;;
+    n|N)
+      local days
+      printf '  How many days back? ' >/dev/tty
+      read -r days </dev/tty
+      if ! [[ "$days" =~ ^[1-9][0-9]*$ ]]; then
+        warn "invalid number — processing all sessions"
+        printf '%s' "$uncurated"
+        return
+      fi
+      local cutoff
+      cutoff="$(date -d "-${days} days" +%Y-%m-%d 2>/dev/null)" || {
+        warn "failed to compute date — processing all sessions"
+        printf '%s' "$uncurated"
+        return
+      }
+      jq -c "[.[] | select(.day_bucket >= \"$cutoff\")]" <<<"$uncurated"
+      ;;
+    o|O)
+      local days_keep
+      printf '  Keep how many days? (dismiss everything older) ' >/dev/tty
+      read -r days_keep </dev/tty
+      if ! [[ "$days_keep" =~ ^[1-9][0-9]*$ ]]; then
+        warn "invalid number — processing all sessions"
+        printf '%s' "$uncurated"
+        return
+      fi
+      local cutoff_keep
+      cutoff_keep="$(date -d "-${days_keep} days" +%Y-%m-%d 2>/dev/null)" || {
+        warn "failed to compute date — processing all sessions"
+        printf '%s' "$uncurated"
+        return
+      }
+      # Dismiss older sessions
+      local old_ids
+      old_ids="$(jq -r "[.[] | select(.day_bucket < \"$cutoff_keep\")] | .[].session_id" <<<"$uncurated")"
+      local dismiss_count=0
+      local old_id
+      while IFS= read -r old_id; do
+        [[ -z "$old_id" ]] && continue
+        clast sessions dismiss "$old_id" --reason "bulk dismiss via clast-wake triage" 2>/dev/null
+        dismiss_count=$(( dismiss_count + 1 ))
+      done <<<"$old_ids"
+      if (( dismiss_count > 0 )); then
+        info "  Dismissed $dismiss_count older session(s)." >/dev/tty
+      fi
+      jq -c "[.[] | select(.day_bucket >= \"$cutoff_keep\")]" <<<"$uncurated"
+      ;;
+    q|Q)
+      printf '[]'
+      ;;
+    *)
+      warn "unknown choice — processing all sessions"
+      printf '%s' "$uncurated"
+      ;;
+  esac
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+
+main() {
+  preflight
+
+  info "Snapshotting fresh transcripts..."
+  if ! clast snapshot 2>/dev/null; then
+    warn "clast snapshot failed — proceeding with existing data"
+  fi
+
+  info "Checking for uncurated or stale sessions..."
+  local sessions_json
+  sessions_json="$(clast --json sessions --since -30d 2>/dev/null)" || {
+    die "failed to list sessions"
+  }
+
+  local uncurated
+  uncurated="$(jq -c '[.[] | select(.curated == false or .stale == true)]' <<<"$sessions_json")"
+  local total
+  total="$(jq 'length' <<<"$uncurated")"
+
+  if (( total == 0 )); then
+    info "Nothing to curate — all sessions are curated or dismissed."
+    exit 0
+  fi
+
+  local day_count first_day last_day project_count
+  day_count="$(jq '[.[].day_bucket] | unique | length' <<<"$uncurated")"
+  first_day="$(jq -r '[.[].day_bucket] | sort | first' <<<"$uncurated")"
+  last_day="$(jq -r '[.[].day_bucket] | sort | last' <<<"$uncurated")"
+  project_count="$(jq '[.[].project] | unique | length' <<<"$uncurated")"
+
+  if (( day_count > 1 )); then
+    uncurated="$(_clast_wake_triage "$uncurated" "$total" "$day_count" "$first_day" "$last_day" "$project_count")"
+    total="$(jq 'length' <<<"$uncurated")"
+    if (( total == 0 )); then
+      info "Nothing left to curate."
+      exit 0
+    fi
+    project_count="$(jq '[.[].project] | unique | length' <<<"$uncurated")"
+  fi
+
+  info "Processing $total session(s) across $project_count project(s)."
+  printf '\n'
+
+  local curated_count=0 skipped_count=0 dismissed_count=0
+  local -a curated_projects=()
+  local i=0 stop=0
+
+  while (( i < total && stop == 0 )); do
+    local session
+    session="$(jq -c ".[$i]" <<<"$uncurated")"
+
+    local sid project branch start_ts end_ts msg_count snapshot_path
+    sid="$(jq -r '.session_id' <<<"$session")"
+    project="$(jq -r '.project' <<<"$session")"
+    branch="$(jq -r '.branch // ""' <<<"$session")"
+    start_ts="$(jq -r '.start' <<<"$session")"
+    end_ts="$(jq -r '.end' <<<"$session")"
+    msg_count="$(jq -r '.msg_count_approx' <<<"$session")"
+    snapshot_path="$(jq -r '.snapshot_path' <<<"$session")"
+
+    local start_short="${start_ts:11:5}"
+    [[ -z "$start_short" ]] && start_short="${start_ts:0:10}"
+
+    local is_stale
+    is_stale="$(jq -r '.stale // false' <<<"$session")"
+    local label="Session $((i+1))/$total: $project"
+    [[ "$is_stale" == "true" ]] && label="$label [STALE]"
+    [[ -n "$start_short" ]] && label="$label ($start_short"
+    [[ -n "$branch" && "$branch" != "null" ]] && label="$label, $branch"
+    label="$label)"
+
+    separator "$label"
+    info "Gathering context..."
+
+    local show_json
+    show_json="$(clast --json show "$sid" --full --turns 8 2>/dev/null)" || {
+      warn "failed to read session $sid — skipping"
+      skipped_count=$(( skipped_count + 1 ))
+      i=$(( i + 1 ))
+      continue
+    }
+
+    local first_turns last_turns
+    first_turns="$(jq -r '
+      .first_turns // [] | .[] |
+      "[\(.role)] \(.text)"
+    ' <<<"$show_json" 2>/dev/null)" || true
+
+    last_turns="$(jq -r '
+      .last_turns // [] | .[] |
+      "[\(.role)] \(.text)"
+    ' <<<"$show_json" 2>/dev/null)" || true
+
+    local breadcrumbs=""
+    breadcrumbs="$(clast breadcrumb --read --project "$project" --day yesterday 2>/dev/null)" || true
+
+    local user_prompt
+    user_prompt="$(build_user_prompt "$project" "$branch" "$start_ts" "$end_ts" "$msg_count" \
+      "$first_turns" "$last_turns" "$breadcrumbs")"
+
+    local system_prompt
+    system_prompt="$(load_system_prompt)"
+
+    local draft="" edit_extra=""
+    local drafting=1
+
+    while (( drafting )); do
+      local full_system="$system_prompt"
+      local full_user="$user_prompt"
+      if [[ -n "$edit_extra" ]]; then
+        full_user="${full_user}
+
+Revisions requested by user: ${edit_extra}"
+      fi
+
+      info "Generating draft..."
+      if ! draft="$(llm_chat "$full_system" "$full_user")"; then
+        printf '\n'
+        warn "LLM call failed for session $sid"
+        local retry
+        printf '  [r] Retry    [s] Skip    [q] Stop\n  Choice: '
+        read -r -n1 retry </dev/tty
+        printf '\n'
+        case "$retry" in
+          r|R) continue ;;
+          q|Q) stop=1; break ;;
+          *) skipped_count=$(( skipped_count + 1 )); break ;;
+        esac
+      fi
+
+      printf '\n%s\n' "$draft"
+      printf '\n'
+
+      local choice
+      choice="$(prompt_choice)"
+
+      case "$choice" in
+        a|A)
+          local title tags body slug
+          title="$(extract_title "$draft")"
+          tags="$(extract_tags "$draft")"
+          body="$(strip_tags_trailer "$draft")"
+          slug="$(get_session_slug "$snapshot_path" "$title")"
+
+          local write_args=(entries write --session "$sid" --slug "$slug" --body-stdin)
+          [[ -n "$tags" ]] && write_args+=(--tags "$tags")
+          [[ -n "$title" ]] && write_args+=(--title "$title")
+
+          local write_result
+          if write_result="$(printf '%s\n' "$body" | clast "${write_args[@]}" 2>&1)"; then
+            info "  $write_result"
+            curated_count=$(( curated_count + 1 ))
+            curated_projects+=("$project")
+          else
+            warn "failed to write entry: $write_result"
+          fi
+          drafting=0
+          ;;
+        e|E)
+          edit_extra="$(prompt_edit_feedback)"
+          ;;
+        d|D)
+          if clast sessions dismiss "$sid" --reason "dismissed via clast-wake" 2>/dev/null; then
+            info "  Dismissed."
+            dismissed_count=$(( dismissed_count + 1 ))
+          else
+            warn "failed to dismiss session $sid"
+          fi
+          drafting=0
+          ;;
+        s|S)
+          skipped_count=$(( skipped_count + 1 ))
+          drafting=0
+          ;;
+        q|Q)
+          stop=1
+          drafting=0
+          ;;
+        *)
+          info "  Unknown choice '$choice' — skipping."
+          skipped_count=$(( skipped_count + 1 ))
+          drafting=0
+          ;;
+      esac
+    done
+
+    i=$(( i + 1 ))
+    printf '\n'
+  done
+
+  local remaining=$(( total - curated_count - skipped_count - dismissed_count ))
+  local unique_projects
+  unique_projects="$(printf '%s\n' "${curated_projects[@]}" 2>/dev/null | sort -u | wc -l | tr -d ' ')" || true
+  [[ -z "$unique_projects" || "$unique_projects" == "0" ]] && unique_projects=0
+
+  printf '\n'
+  separator "Summary"
+  info "  Curated: $curated_count session(s) across $unique_projects project(s)"
+  if (( dismissed_count > 0 )); then
+    info "  Dismissed: $dismissed_count session(s)"
+  fi
+  info "  Skipped: $skipped_count session(s)"
+  if (( remaining > 0 )); then
+    info "  Remaining: $remaining session(s) (stopped early)"
+  fi
+}
+
+main "$@"

package/hooks/snapshot.sh

@@ -1,15 +1,23 @@
 #!/usr/bin/env bash
-# hooks/snapshot.sh
-#
-# Fired on Claude Code SessionStart. Backgrounds `clast snapshot` so it doesn't
-# block session start. Silent if clast isn't installed — the plugin can still
-# load cleanly even if the CLI isn't on PATH.
-#
-# Idempotent. Safe to run repeatedly. Best-effort: never propagates a non-zero
-# exit to Claude Code (a failed snapshot is not a session-start failure).
+# hooks/snapshot.sh — SessionStart hook. Backgrounds `clast snapshot`.
+# Idempotent. Best-effort: never propagates a non-zero exit.
 # shellcheck shell=bash
 
-if command -v clast >/dev/null 2>&1; then
-  (clast snapshot >/dev/null 2>&1 &)
+# Derive plugin root from this script's location.
+# $0 is the expanded path from ${CLAUDE_PLUGIN_ROOT}/hooks/snapshot.sh.
+_snap_dir="$(cd "$(dirname "$0")" && pwd)"
+_plugin_root="$(cd "$_snap_dir/.." && pwd)"
+
+# Prefer the bundled binary (version-matched to this plugin).
+# Fall back to a system-level install on PATH.
+_clast=""
+if [[ -x "$_plugin_root/bin/clast" ]]; then
+  _clast="$_plugin_root/bin/clast"
+elif command -v clast >/dev/null 2>&1; then
+  _clast="clast"
+fi
+
+if [[ -n "$_clast" ]]; then
+  ($_clast snapshot >/dev/null 2>&1 &)
 fi
 exit 0

package/lib/clast/clast-decode-lib.bash

@@ -6,8 +6,8 @@
 # segment, identical to a path separator. Decoding ambiguity is resolved
 # against the filesystem (and, for git repos, a `git rev-parse` probe).
 #
-# See docs/overview.md#glossary for the "segment" term and
-# docs/repo-bootstrap.md#libclastclast-decode-libbash for the algorithm.
+# See docs/explanation/data-model.md for the "segment" term and
+# docs/reference/repo-bootstrap.md#libclastclast-decode-libbash for the algorithm.
 # shellcheck shell=bash
 
 if [[ -n "${_CLAST_DECODE_LIB_SOURCED:-}" ]]; then

package/lib/clast/clast-dismissed-lib.bash

@@ -0,0 +1,73 @@
+# clast-dismissed-lib.bash — dismissed session tracking
+#
+# Thin layer over $(clast_journal_dir)/.dismissed.jsonl. Each line
+# records a session_id + timestamp. Used by sessions.bash to exclude
+# throwaway sessions from query results.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+
+if [[ -n "${_CLAST_DISMISSED_LIB_SOURCED:-}" ]]; then
+  return 0
+fi
+_CLAST_DISMISSED_LIB_SOURCED=1
+
+clast_dismissed_path() {
+  printf '%s\n' "$(clast_journal_dir)/.dismissed.jsonl"
+}
+
+# clast_dismissed_add <session-id> [reason]
+clast_dismissed_add() {
+  local session_id="$1"
+  local reason="${2:-}"
+  if [[ -z "$session_id" ]]; then
+    clast_log_error "clast_dismissed_add: empty session_id"
+    return 2
+  fi
+
+  local dismissed_file
+  dismissed_file="$(clast_dismissed_path)"
+
+  local now
+  now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  local line
+  line="$(jq -cn \
+    --arg sid "$session_id" \
+    --arg ts "$now" \
+    --arg reason "$reason" \
+    '{session_id: $sid, dismissed_at: $ts, reason: (if $reason == "" then null else $reason end)}')"
+
+  printf '%s\n' "$line" >> "$dismissed_file"
+}
+
+# clast_dismissed_set — populate an associative array with dismissed IDs.
+# Usage: declare -A dismissed=(); clast_dismissed_set dismissed
+clast_dismissed_set() {
+  local -n _ref=$1
+  local dismissed_file
+  dismissed_file="$(clast_dismissed_path)"
+
+  if [[ ! -f "$dismissed_file" ]]; then
+    return 0
+  fi
+
+  local line sid
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    sid="$(jq -r '.session_id // empty' <<<"$line" 2>/dev/null)" || continue
+    [[ -n "$sid" ]] && _ref["$sid"]=1
+  done < "$dismissed_file"
+}
+
+# clast_dismissed_check <session-id> — exit 0 if dismissed, 1 if not.
+clast_dismissed_check() {
+  local session_id="$1"
+  local dismissed_file
+  dismissed_file="$(clast_dismissed_path)"
+
+  if [[ ! -f "$dismissed_file" ]]; then
+    return 1
+  fi
+
+  grep -q "\"session_id\":\"$session_id\"" "$dismissed_file" 2>/dev/null
+}