@procrastivity/clast 0.0.4 → 0.0.6

package/lib/clast/clast-porcelain-subcommands/brief.bash

@@ -1,6 +1,6 @@
 # clast brief — LLM-powered project briefing.
 #
-# Replicates the /wakeup plugin skill using an OpenAI-compatible chat
+# Replicates the /brief plugin skill using an OpenAI-compatible chat
 # completions endpoint. Reads curated entries, breadcrumbs, and today's
 # sessions for a project (via clast-plumbing), then synthesizes a briefing.
 #
@@ -30,38 +30,94 @@ _clast_brief_resolve_project() {
 
 # --- Gather data -------------------------------------------------------------
 
+# Group key for an entry: per-directory label, else branch, else "default".
+# A slug may span several directories; grouping keeps their work distinct
+# instead of letting the single newest entry stand in for the whole project.
 _clast_brief_gather_entries() {
-  local project="$1"
+  local project="$1" current_label="${2:-}"
+
+  # Pull the full entries list (no global cap). A global `--limit` here would
+  # let one busy clone with N newer entries push the current clone out of the
+  # window entirely before we ever see it — even though the per-group/total
+  # caps below already keep the prompt within the brief's token budget.
   local entries_json
-  entries_json="$(clast-plumbing --json entries --project "$project" --limit 5 2>/dev/null)" || true
+  entries_json="$(clast-plumbing --json entries --project "$project" 2>/dev/null)" || true
 
   if [[ -z "$entries_json" ]] || [[ "$(jq 'length' <<<"$entries_json" 2>/dev/null)" == "0" ]]; then
     return
   fi
 
-  local n i entry_meta entry_path entry_body result=""
-  n="$(jq 'length' <<<"$entries_json")"
+  # Ordered, de-duplicated group keys in newest-first order of first
+  # appearance (entries list is already sorted newest-first). If a
+  # current_label was provided AND it appears in the entries, hoist it to
+  # the front so the active thread gets its share before total_cap is hit.
+  local -a groups=()
+  mapfile -t groups < <(jq -r --arg cur "$current_label" '
+    [ .[] | (.label // .branch // "default") ] as $keys
+    | (reduce $keys[] as $k ([]; if index($k) then . else . + [$k] end)) as $uniq
+    | (if $cur != "" and ($uniq | index($cur)) != null
+         then [$cur] + ($uniq - [$cur])
+         else $uniq end)
+    | .[]
+  ' <<<"$entries_json")
+
+  # A single-workspace project renders exactly as before (no group headers),
+  # so this change is a strict superset for the common case.
+  local single_group=0
+  (( ${#groups[@]} <= 1 )) && single_group=1
+
+  # Per-group and total caps keep the prompt within the brief's token budget.
+  local per_group=3 total_cap=8 emitted=0
+  local result="" g
+
+  for g in "${groups[@]}"; do
+    (( emitted >= total_cap )) && break
+
+    local -a paths=()
+    mapfile -t paths < <(jq -r --arg g "$g" --argjson per "$per_group" '
+      [ .[] | select((.label // .branch // "default") == $g) ][0:$per] | .[].path
+    ' <<<"$entries_json")
+    (( ${#paths[@]} == 0 )) && continue
+
+    # Build this group's body first, so we can skip the header if nothing reads.
+    local group_block="" p entry_body
+    for p in "${paths[@]}"; do
+      (( emitted >= total_cap )) && break
+      entry_body="$(clast-plumbing entries read "$p" 2>/dev/null)" || true
+      if [[ -z "$entry_body" ]]; then continue; fi
+      if [[ -n "$group_block" ]]; then
+        group_block="${group_block}
 
-  for (( i = 0; i < n; i++ )); do
-    entry_meta="$(jq -c ".[$i]" <<<"$entries_json")"
-    entry_path="$(jq -r '.path' <<<"$entry_meta")"
+---
 
-    entry_body="$(clast-plumbing entries read "$entry_path" 2>/dev/null)" || true
-    if [[ -z "$entry_body" ]]; then
-      local title date
-      title="$(jq -r '.title // "untitled"' <<<"$entry_meta")"
-      date="$(jq -r '.date' <<<"$entry_meta")"
-      entry_body="# $date — $title (body not available)"
+"
+      fi
+      group_block="${group_block}${entry_body}"
+      emitted=$(( emitted + 1 ))
+    done
+    [[ -z "$group_block" ]] && continue
+
+    local block="$group_block"
+    if (( single_group == 0 )); then
+      local branch_disp
+      branch_disp="$(jq -r --arg g "$g" '
+        [ .[] | select((.label // .branch // "default") == $g) ][0].branch // ""
+      ' <<<"$entries_json")"
+      local header="## Workspace: $g"
+      if [[ -n "$branch_disp" && "$branch_disp" != "null" ]]; then
+        header="$header (branch: $branch_disp)"
+      fi
+      block="${header}
+
+${group_block}"
     fi
 
     if [[ -n "$result" ]]; then
       result="${result}
 
----
-
 "
     fi
-    result="${result}${entry_body}"
+    result="${result}${block}"
   done
 
   printf '%s' "$result"
@@ -73,6 +129,9 @@ _clast_brief_gather_breadcrumbs() {
 }
 
 _clast_brief_gather_sessions() {
+  # NOTE: today's sessions come from the manifest, not curated entries, so
+  # they are not (yet) grouped by workspace label the way entries are. Per-
+  # directory session grouping is a possible follow-up.
   local project="$1"
   local sessions_json
   sessions_json="$(clast-plumbing --json sessions --day today --project "$project" 2>/dev/null)" || true
@@ -100,7 +159,7 @@ _clast_brief_gather_sessions() {
 # --- User prompt -------------------------------------------------------------
 
 _clast_brief_build_user_prompt() {
-  local project="$1" entries="$2" breadcrumbs="$3" sessions="$4"
+  local project="$1" entries="$2" breadcrumbs="$3" sessions="$4" current_label="$5"
 
   local template_file template
   template_file="$(clast_porcelain_user_prompt_file brief-user)"
@@ -108,6 +167,7 @@ _clast_brief_build_user_prompt() {
   if [[ -n "$template_file" ]]; then
     template="$(cat "$template_file")"
     template="${template//\{\{project\}\}/${project}}"
+    template="${template//\{\{current_label\}\}/${current_label:-unknown}}"
     template="${template//\{\{entries\}\}/${entries:-None.}}"
     template="${template//\{\{breadcrumbs\}\}/${breadcrumbs:-None.}}"
     template="${template//\{\{sessions\}\}/${sessions:-None.}}"
@@ -116,8 +176,9 @@ _clast_brief_build_user_prompt() {
     clast_porcelain_warn "user prompt template not found: brief-user.md — using inline fallback"
     cat <<EOF
 Project: ${project}
+Current workspace (the directory you are in now): ${current_label:-unknown}
 
-Recent curated entries (newest first):
+Recent curated entries, grouped by workspace (newest first):
 ${entries:-None.}
 
 Today's breadcrumbs for this project:
@@ -138,10 +199,18 @@ clast_cmd_brief() {
   project="$(_clast_brief_resolve_project "${1:-}")"
   clast_porcelain_info "Briefing for project: $project"
 
+  # When the project was resolved from the current directory (no positional
+  # slug), find that directory's workspace label so the briefing can prefer
+  # the active thread for the clone the user is actually in.
+  local current_label=""
+  if [[ -z "${1:-}" ]]; then
+    current_label="$(clast-plumbing registry resolve "$(pwd)" --json 2>/dev/null | jq -r '.label // empty' 2>/dev/null)" || true
+  fi
+
   clast_porcelain_info "Gathering context..."
 
   local entries breadcrumbs sessions
-  entries="$(_clast_brief_gather_entries "$project")"
+  entries="$(_clast_brief_gather_entries "$project" "$current_label")"
   breadcrumbs="$(_clast_brief_gather_breadcrumbs "$project")"
   sessions="$(_clast_brief_gather_sessions "$project")"
 
@@ -153,7 +222,7 @@ clast_cmd_brief() {
 
   local system_prompt user_prompt
   system_prompt="$(clast_porcelain_load_system_prompt brief-system)"
-  user_prompt="$(_clast_brief_build_user_prompt "$project" "$entries" "$breadcrumbs" "$sessions")"
+  user_prompt="$(_clast_brief_build_user_prompt "$project" "$entries" "$breadcrumbs" "$sessions" "$current_label")"
 
   clast_porcelain_info "Synthesizing briefing..."
   printf '\n'

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

@@ -0,0 +1,317 @@
+# clast retro — LLM-condensed work retrospective grouped by work day → project.
+#
+# Round 2 of the retro feature. Structure comes from the deterministic core
+# (`clast-plumbing retro --json --bodies`); the model only condenses each
+# session's body into a few retro bullets. Summaries are cached per session_id
+# (content-fingerprinted) under the journal dir, so re-runs are free unless a
+# session changed or --refresh is passed. See .wip/initiatives/clast-retro/.
+# shellcheck shell=bash
+
+_clast_retrosum_usage() {
+  cat <<'EOF'
+Usage: clast retro [--from DATE] [--to DATE] [--all]
+                   [--window work-days|file-dates] [--refresh] [--json]
+
+Condense the work retrospective (grouped by actual work day → project) into
+model-written bullets per session. Structure is deterministic; only the prose
+condensation calls the LLM. Summaries are cached per session under
+<journal>/.retro-summaries/ and reused until the session content changes.
+
+With no window flags, defaults to the last 7 days (one model call per new
+session, so an unbounded run over the whole corpus can be slow and costly).
+
+Flags:
+  --from DATE     Start of the window (inclusive). Default: 7 days ago.
+  --to DATE       End of the window (inclusive). Default: corpus end.
+  --all           Cover the whole corpus (overrides the 7-day default).
+  --window WHICH  work-days (default) | file-dates. See `clast-plumbing retro`.
+  --refresh       Ignore cached summaries and re-summarize (rewrites the cache).
+  --json          Emit the manifest with a `summary` per session (no render).
+  -h, --help      Print this usage and exit.
+
+DATE accepts ISO (YYYY-MM-DD), `today`, `yesterday`, `last-week`, `-Nd`, `-Nw`.
+
+Requires the CLAST_LLM_* env vars (see `clast --help`).
+EOF
+}
+
+# _clast_retro_progress <msg>
+#   Emit a progress line to stderr so stdout (render or --json) stays clean.
+#   Silent when CLAST_QUIET is set or stderr is not a TTY; CLAST_RETRO_PROGRESS=always
+#   forces it on (used by tests, which have no tty).
+_clast_retro_progress() {
+  [[ -n "${CLAST_QUIET:-}" ]] && return 0
+  if [[ "${CLAST_RETRO_PROGRESS:-}" == "always" || -t 2 ]]; then
+    printf 'clast: %s\n' "$*" >&2
+  fi
+}
+
+# _clast_retro_now — epoch seconds with fraction (GNU date). Falls back to whole
+# seconds where `%N` is unsupported (e.g. BSD/macOS date echoes a literal N).
+_clast_retro_now() {
+  local t
+  t="$(date +%s.%N 2>/dev/null)" || t="$(date +%s)"
+  [[ "$t" == *N* ]] && t="$(date +%s)"
+  printf '%s' "$t"
+}
+
+# _clast_retro_elapsed <start> <end> — seconds between two _clast_retro_now
+# readings, one decimal place (never negative).
+_clast_retro_elapsed() {
+  awk -v a="$1" -v b="$2" 'BEGIN { d = b - a; if (d < 0) d = 0; printf "%.1f", d }'
+}
+
+# _clast_retrosum_fingerprint  (stdin → short hex/cksum on stdout)
+#   Content fingerprint of a session body; changes invalidate the cache.
+_clast_retrosum_fingerprint() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | cut -c1-16
+  else
+    cksum | awk '{print $1}'
+  fi
+}
+
+# _clast_retrosum_build_user <project> <work_day> <session_id> <body>
+_clast_retrosum_build_user() {
+  local project="$1" work_day="$2" sid="$3" body="$4"
+  local tf tpl
+  tf="$(clast_porcelain_user_prompt_file retro-summary-user)"
+  if [[ -n "$tf" ]]; then
+    tpl="$(cat "$tf")"
+    tpl="${tpl//\{\{project\}\}/$project}"
+    tpl="${tpl//\{\{work_day\}\}/$work_day}"
+    tpl="${tpl//\{\{session_id\}\}/$sid}"
+    tpl="${tpl//\{\{body\}\}/$body}"
+    printf '%s' "$tpl"
+  else
+    printf 'Project: %s\nWork day: %s\nSession id: %s\n\nEntry body:\n%s\n' \
+      "$project" "$work_day" "$sid" "$body"
+  fi
+}
+
+# _clast_retrosum_summary <project> <work_day> <session_id> <body> <cache_dir> <refresh>
+#   Echo the condensed summary. Return code tells the caller what happened so it
+#   can time only the calls that hit the model:
+#     0 — served from cache (no model call)
+#     3 — fresh summary via a model call (success)
+#     1 — model call failed
+_clast_retrosum_summary() {
+  local project="$1" work_day="$2" sid="$3" body="$4" cache_dir="$5" refresh="$6"
+  local fp cache_file cached_fp
+  fp="$(printf '%s' "$body" | _clast_retrosum_fingerprint)"
+  cache_file="$cache_dir/$sid.json"
+
+  if (( ! refresh )) && [[ -r "$cache_file" ]]; then
+    cached_fp="$(jq -r '.fingerprint // empty' "$cache_file" 2>/dev/null)"
+    if [[ -n "$cached_fp" && "$cached_fp" == "$fp" ]]; then
+      jq -r '.summary // empty' "$cache_file"
+      return 0
+    fi
+  fi
+
+  _clast_retro_progress "        querying model..."
+  local system user summary
+  system="$(clast_porcelain_load_system_prompt retro-summary-system)"
+  user="$(_clast_retrosum_build_user "$project" "$work_day" "$sid" "$body")"
+  if ! summary="$(clast_porcelain_llm_chat "$system" "$user")"; then
+    return 1
+  fi
+
+  if mkdir -p "$cache_dir" 2>/dev/null; then
+    jq -n --arg fp "$fp" --arg s "$summary" '{fingerprint:$fp, summary:$s}' \
+      >"$cache_file" 2>/dev/null || clast_porcelain_warn "failed to cache summary for $sid"
+  fi
+  printf '%s' "$summary"
+  return 3
+}
+
+# _clast_retrosum_journal_dir — resolve the journal dir (for the cache).
+_clast_retrosum_journal_dir() {
+  if [[ -n "${CLAST_JOURNAL_DIR:-}" ]]; then
+    printf '%s' "$CLAST_JOURNAL_DIR"
+    return
+  fi
+  local jd
+  jd="$(clast-plumbing whereami 2>/dev/null | awk '/^journal_dir:/{print $2}')" || true
+  printf '%s' "${jd:-$HOME/.claude/journal}"
+}
+
+clast_cmd_retro() {
+  local from="" to="" window="work-days" refresh=0 as_json=0 all=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --from)     [[ $# -lt 2 ]] && { clast_porcelain_log_error "retro: --from requires a value"; return 2; }; from="$2"; shift 2 ;;
+      --from=*)   from="${1#*=}"; shift ;;
+      --to)       [[ $# -lt 2 ]] && { clast_porcelain_log_error "retro: --to requires a value"; return 2; }; to="$2"; shift 2 ;;
+      --to=*)     to="${1#*=}"; shift ;;
+      --all)      all=1; shift ;;
+      --window)   [[ $# -lt 2 ]] && { clast_porcelain_log_error "retro: --window requires a value"; return 2; }; window="$2"; shift 2 ;;
+      --window=*) window="${1#*=}"; shift ;;
+      --refresh)  refresh=1; shift ;;
+      --json)     as_json=1; shift ;;
+      -h|--help)  _clast_retrosum_usage; return 0 ;;
+      --) shift; break ;;
+      *) clast_porcelain_log_error "retro: unknown argument '$1'"; return 2 ;;
+    esac
+  done
+
+  # An unbounded retro means one model call per session across the whole corpus
+  # (slow and costly). Default to the last 7 days unless the caller bounded the
+  # window themselves (--from/--to) or opted into everything with --all.
+  if (( ! all )) && [[ -z "$from" && -z "$to" ]]; then
+    from="-7d"
+  fi
+
+  clast_porcelain_preflight_llm
+
+  # Structure + per-session bodies from the deterministic core.
+  _clast_retro_progress "building work-day manifest..."
+  local -a pl=(--json retro --bodies --window "$window")
+  [[ -n "$from" ]] && pl+=(--from "$from")
+  [[ -n "$to" ]] && pl+=(--to "$to")
+  local manifest
+  if ! manifest="$(clast-plumbing "${pl[@]}" 2>/dev/null)"; then
+    local msg
+    msg="$(jq -r '.error // empty' <<<"$manifest" 2>/dev/null || true)"
+    clast_porcelain_die "retro: ${msg:-failed to build manifest}" 2
+  fi
+
+  # Report the resolved window + discovered work days before the slow summarize
+  # loop — the "dates it resolved to" the user wants to see up front.
+  local pf pt pw ndays nsess daylist
+  pf="$(jq -r '.from // "(start)"'  <<<"$manifest")"
+  pt="$(jq -r '.to   // "(end)"'    <<<"$manifest")"
+  pw="$(jq -r '.window'             <<<"$manifest")"
+  ndays="$(jq '.days | length'      <<<"$manifest")"
+  nsess="$(jq '[.days[].projects[].sessions[]] | length' <<<"$manifest")"
+  daylist="$(jq -r '[.days[].day] | join(", ")' <<<"$manifest")"
+  _clast_retro_progress "window: $pf -> $pt ($pw)"
+  _clast_retro_progress "resolved $nsess session(s) across $ndays day(s): $daylist"
+
+  local cache_dir
+  cache_dir="$(_clast_retrosum_journal_dir)/.retro-summaries"
+
+  # Summarize each session; collect key → summary.
+  local -a summary_pairs=()
+  local sess sid key cache_id project work_day body title summary pname
+  local t0 t1 dt rc
+  local idx=0 total="$nsess" queried=0 model_total="0.0"
+  while IFS= read -r sess; do
+    [[ -z "$sess" ]] && continue
+    sid="$(jq -r '.session_id // ""' <<<"$sess")"
+    # Fold key: session_id, or the unique first entry path for id-less sessions
+    # (must match the plumbing manifest's key so summaries fold back correctly
+    # and two id-less sessions don't collide on a shared "null" key).
+    key="$(jq -r '.session_id // .entries[0]' <<<"$sess")"
+    # Cache filename must be unique and filesystem-safe even without an id.
+    if [[ -n "$sid" ]]; then
+      cache_id="$sid"
+    else
+      cache_id="noid-$(printf '%s' "$key" | _clast_retrosum_fingerprint)"
+    fi
+    work_day="$(jq -r '.work_day' <<<"$sess")"
+    body="$(jq -r '.body // ""' <<<"$sess")"
+    project="$(jq -r '.project_path // "(no project)"' <<<"$sess")"
+    idx=$(( idx + 1 ))
+    pname="$(jq -r '.progress_project // .project_path // "(no project)"' <<<"$sess")"
+    title="$(jq -r '.title // ""' <<<"$sess")"
+    _clast_retro_progress "[$idx/$total] $work_day  $pname  ${title:-${sid:0:8}}"
+    if [[ -z "$body" ]]; then
+      summary="(no body to summarize)"
+    else
+      # Time the call so we can report how long the model took. rc distinguishes
+      # a cache hit (0, instant) from a fresh model call (3) from a failure.
+      rc=0
+      t0="$(_clast_retro_now)"
+      summary="$(_clast_retrosum_summary "$project" "$work_day" "$cache_id" "$body" "$cache_dir" "$refresh")" || rc=$?
+      t1="$(_clast_retro_now)"
+      case "$rc" in
+        0) : ;;  # served from cache — no model call, nothing to time
+        3) dt="$(_clast_retro_elapsed "$t0" "$t1")"
+           queried=$(( queried + 1 ))
+           model_total="$(awk -v a="$model_total" -v d="$dt" 'BEGIN { printf "%.1f", a + d }')"
+           _clast_retro_progress "        done in ${dt}s (model total ${model_total}s)" ;;
+        *) clast_porcelain_warn "summary failed for session ${sid:-<no id>} — leaving it unsummarized"
+           summary="(summary unavailable)" ;;
+      esac
+    fi
+    summary_pairs+=("$(jq -cn --arg k "$key" --arg v "$summary" '{key:$k, summary:$v}')")
+  done < <(jq -c '.days[].projects[] | .project_name as $pn | .sessions[] | . + {progress_project: $pn}' <<<"$manifest")
+
+  if (( total > 0 )); then
+    _clast_retro_progress "summarized $total session(s); $queried queried the model (${model_total}s)"
+  fi
+
+  # Fold summaries back into the manifest and drop the raw bodies. The manifest
+  # carries --bodies only as summarizer input; neither the JSON nor the render
+  # path consumes .body, so strip it here to keep --json condensed and
+  # consistent with the plumbing's lean-by-default output (raw bodies remain
+  # available via `clast-plumbing --json retro --bodies`). The manifest can
+  # exceed MAX_ARG_STRLEN — feed it via stdin and the summary pairs via
+  # --slurpfile, never argv.
+  local enriched="$manifest"
+  if (( ${#summary_pairs[@]} > 0 )); then
+    # Key by `session_id // .entries[0]` (always a non-null string), matching
+    # the pairs above: this can't abort jq on a null id and keeps two id-less
+    # sessions distinct instead of collapsing them onto a shared key.
+    enriched="$(printf '%s' "$manifest" | jq -c --slurpfile pairs <(printf '%s\n' "${summary_pairs[@]}") '
+      (reduce $pairs[] as $p ({}; .[$p.key] = $p.summary)) as $sum
+      | .days |= map(.projects |= map(.sessions |= map(
+          del(.body) + {summary: ($sum[(.session_id // .entries[0])] // null)})))
+    ')"
+  fi
+
+  if (( as_json )); then
+    printf '%s\n' "$enriched"
+    return 0
+  fi
+
+  _clast_retrosum_render "$enriched"
+}
+
+# _clast_retrosum_render <manifest-with-summaries>
+_clast_retrosum_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 day np project ns sess sid shortsid title summary note flag
+  for (( di = 0; di < nd; di++ )); do
+    day="$(jq -r ".days[$di].day" <<<"$manifest")"
+    printf '\n== %s ==\n' "$day"
+    note="$(jq -r --arg d "$day" '.days['"$di"'].curation_dates // [] |
+      if . == [] or . == [$d] then empty
+      else "  (filed " + (join(", ")) + "; work day reconstructed from session snapshots)"
+      end' <<<"$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}"
+        title="$(jq -r '.title // "(untitled)"' <<<"$sess")"
+        [[ -z "$title" || "$title" == "null" ]] && title="(untitled)"
+        summary="$(jq -r '.summary // "(no summary)"' <<<"$sess")"
+        flag=""
+        [[ "$(jq -r '.interrupted // false' <<<"$sess")" == "true" ]] && flag="  [interrupted]"
+        printf '\n  * %s  (%s)%s\n' "$title" "$shortsid" "$flag"
+        printf '%s\n' "$summary"
+      done
+    done
+  done
+}

package/lib/clast/clast-porcelain-subcommands/undismiss.bash

@@ -0,0 +1,27 @@
+# clast undismiss — restore session(s) dismissed during `clast wake`.
+#
+# A convenience verb over `clast-plumbing sessions undismiss`: `clast wake`
+# now prints each session's id, so recovering an accidental [d] is a direct
+# `clast undismiss <id>` without dropping down to the plumbing surface.
+# shellcheck shell=bash
+
+clast_cmd_undismiss() {
+  case "${1:-}" in
+    -h|--help)
+      cat <<'EOF'
+Usage: clast undismiss <session-id> [<session-id>...]
+
+Restore session(s) previously dismissed (e.g. an accidental [d] in
+`clast wake`). Session ids are shown in the `clast wake` review header.
+EOF
+      return 0
+      ;;
+  esac
+
+  if ! command -v clast-plumbing >/dev/null 2>&1; then
+    clast_porcelain_die "required tool not found: clast-plumbing"
+  fi
+
+  # Thin passthrough: plumbing owns UUID validation and JSON/human output.
+  clast-plumbing sessions undismiss "$@"
+}