@thebassclef/lite 1.0.0 → 1.0.2

package/dist/lite/.claude/hooks/session-end.sh

@@ -0,0 +1,433 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Session End hook — fires on Stop event.
+# Requires Claude to run session-end protocol, then auto-saves state.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/trace-helper.sh"
+trace_log "session-end" "stop event"
+
+# Compute deterministic session timing
+CWD=$(pwd)
+CWD_HASH=$(echo -n "$CWD" | md5 -q 2>/dev/null || echo -n "$CWD" | md5sum 2>/dev/null | cut -c1-8 || echo "default")
+SESSION_TIMING_FILE="/tmp/claude-session-timing-${CWD_HASH}"
+ENDED_AT=$(date +"%Y-%m-%dT%H:%M:%S%z")
+
+if [ -f "$SESSION_TIMING_FILE" ]; then
+  STARTED_AT=$(cat "$SESSION_TIMING_FILE")
+  START_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$STARTED_AT" +%s 2>/dev/null || date -d "$STARTED_AT" +%s 2>/dev/null || echo "")
+  END_EPOCH=$(date +%s)
+  if [ -n "$START_EPOCH" ]; then
+    DURATION_SEC=$((END_EPOCH - START_EPOCH))
+    DURATION_MIN=$((DURATION_SEC / 60))
+  fi
+fi
+
+cat <<END
+============================================
+SESSION END — RUN /session-end
+============================================
+
+### Session Timing (deterministic — from hooks)
+- started_at: ${STARTED_AT:-unknown}
+- ended_at: ${ENDED_AT}
+- duration_minutes: ${DURATION_MIN:-unknown}
+
+Use these EXACT values in the chronicle frontmatter. Do NOT estimate.
+============================================
+
+Run the /session-end skill now. It handles tiered obligations:
+
+**Must** (local, no network — always complete these):
+  1. Clean working tree (commit or stash)
+  2. Chronicle entry (chronicle/ or docs/chronicle/)
+  3. Memory update
+  4. Remove session lock
+
+**Should** (network needed — log failures, don't block):
+  5. Git push
+  6. Update whereami.md
+  7. LinkedIn draft (if a decision, trade-off, or insight shipped)
+
+**May** (conditional — skip without guilt if time is short):
+  8. Danger mode summary (if auto-complete used)
+  9. Release notes (if user-facing changes deployed)
+
+Do NOT skip the Must tier. The save-state hook runs automatically
+after this prompt, but the chronicle and memory are YOUR job.
+============================================
+END
+
+# Auto-save state on session end
+# Log failures visibly per standards/hook-idempotency.md — don't swallow
+#
+# === Guard 0: SESSION_LOCK precedence for save-state (bet 27b Step 2; ADR-046) ===
+#
+# When an autonomous /longrun session is active, SESSION_LOCK is held.
+# Stop hook fires many times per session — not just at true session-end.
+# Calling save-state.sh on every Stop pollutes feature branches with
+# unwanted commits (bet 27a Way 2 mechanism).
+#
+# The autonomous session owns its own commits via explicit /session-end
+# invocation. When SESSION_LOCK is held by another process group (foreign
+# PGID), skip save-state here. Same-PGID lock is our own — proceed normally
+# (save-state.sh clears it at the end).
+#
+# Held-by-self case is intentional: at real session-end, the autonomous
+# session explicitly invokes /session-end which reaches this hook via a
+# process in our own PGID. Guard 0 lets that path through.
+LOCK_FILE_GUARD0="${CWD:-.}/.claude/SESSION_LOCK"
+if [ -f "$LOCK_FILE_GUARD0" ]; then
+  G0_PID=$(grep -E '^pid:' "$LOCK_FILE_GUARD0" 2>/dev/null | head -1 | sed -E 's/^pid:[[:space:]]*//' | tr -d '[:space:]')
+  if [ -n "$G0_PID" ]; then
+    G0_PGID=$(ps -o pgid= -p "$G0_PID" 2>/dev/null | tr -d ' ')
+    G0_OUR_PGID=$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')
+    if [ -n "$G0_PGID" ] && [ -n "$G0_OUR_PGID" ] && [ "$G0_PGID" != "$G0_OUR_PGID" ]; then
+      echo "SESSION_LOCK held by pid $G0_PID (foreign PGID) — skipping save-state per ADR-046 (autonomous session owns own commits)"
+      SKIP_SAVE_STATE_G0=1
+    fi
+  fi
+fi
+
+if [ "${SKIP_SAVE_STATE_G0:-0}" = "0" ]; then
+  "$SCRIPT_DIR/save-state.sh" --quiet 2>&1 || echo "WARNING: save-state failed (non-blocking)"
+fi
+
+# === Session-rescue on abrupt stop (bassclef #226 WS-3) ===
+#
+# If the agent hit Stop without fulfilling MUST-tier session-end
+# obligations (chronicle for today, whereami fresh, git clean), leave
+# a forward-pointer deferred-action entry so the next capable session
+# picks up the unfinished work. See .claude/rules/session-artifacts.md
+# and docs/deferred-actions/README.md.
+#
+# Detection is conservative — false positives (extra rescue entry on a
+# clean session-end) are harmless (next session sees the entry, checks
+# obligations are met, `git mv`'s to completed/). False negatives
+# (missing rescue when obligations were actually unmet) are the
+# failure mode we're trying to avoid.
+
+TODAY=$(date +"%Y-%m-%d")
+NEEDS_RESCUE=0
+RESCUE_REASONS=""
+
+# Chronicle check — session-relative, NOT UTC-calendar-date.
+#
+# Prior shape ("chronicle for ${TODAY} exists?") produced the
+# 2026-04-21 self-amplifying rescue loop: prior session ended
+# 2026-04-21T00:40 local (2026-04-20T23:40 UTC) and wrote a chronicle
+# dated 2026-04-20; next Stop firing at 00:10 UTC next day saw "no
+# chronicle for 2026-04-21" → wrote rescue → auto-save → Stop →
+# loop. The session-relative shape: did the most recent chronicle
+# capture work from within this session's window? "Last 24 hours of
+# mtime" is the simplest correct approximation — crosses midnight
+# freely, still fires when chronicles are genuinely missing.
+CHRONICLE_DIR=""
+if [ -d "$CWD/chronicle" ]; then
+  CHRONICLE_DIR="$CWD/chronicle"
+elif [ -d "$CWD/docs/chronicle" ]; then
+  CHRONICLE_DIR="$CWD/docs/chronicle"
+fi
+if [ -n "$CHRONICLE_DIR" ]; then
+  if ! find "$CHRONICLE_DIR" -maxdepth 1 -name "*.md" -type f -mtime -1 2>/dev/null | grep -q .; then
+    NEEDS_RESCUE=1
+    RESCUE_REASONS="${RESCUE_REASONS}- no chronicle written or updated in last 24h\n"
+  fi
+fi
+
+# Uncommitted-changes check (from CWD) — with self-output suppression.
+#
+# Without the guard, the rescue hook's own writes (entries dropped
+# into docs/deferred-actions/*-session-rescue.md) count as
+# "uncommitted changes" on the NEXT firing. auto-save commits them,
+# next Stop sees chronicle-missing or other signal, writes ANOTHER
+# rescue → auto-save → ... (2026-04-21 overnight: 16 entries).
+#
+# Fix: when the only uncommitted paths are rescue entries this hook
+# itself produces, treat working tree as clean. Non-rescue content
+# (real work, other deferred-action types) still fires rescue.
+if [ -d "$CWD/.git" ] || git -C "$CWD" rev-parse --git-dir >/dev/null 2>&1; then
+  # -u (untracked-files=all) expands untracked-directory entries into
+  # their individual files. Default mode collapses e.g. an untracked
+  # docs/deferred-actions/ to "?? docs/", which would defeat the path-
+  # level filter below.
+  DIRTY_STATUS=$(git -C "$CWD" status --porcelain -u 2>/dev/null)
+  if [ -n "$DIRTY_STATUS" ]; then
+    # Strip porcelain prefix (first 3 chars = "XY ") to get paths.
+    # Keep only lines whose path is NOT a session-rescue entry.
+    NON_RESCUE=$(echo "$DIRTY_STATUS" | awk '{print substr($0, 4)}' | grep -v '^docs/deferred-actions/[^/]*-session-rescue\.md$' || true)
+    if [ -n "$NON_RESCUE" ]; then
+      NEEDS_RESCUE=1
+      RESCUE_REASONS="${RESCUE_REASONS}- uncommitted changes in working tree\n"
+    fi
+  fi
+fi
+
+# Whereami freshness check (last_updated within last 24h).
+#
+# Read the FIRST ISO date-prefix line in the `## Last updated` section,
+# not `tail -1` across the whole file. The changelog under `## Last
+# updated` grows over time with newest entries prepended at top —
+# `tail -1` grabbed the OLDEST entry and falsely flagged the file as
+# stale on every Stop, producing self-amplifying rescue loops (observed
+# 2026-04-24: 24d session-end at 12:36 → false rescue at 12:39 against
+# a freshly-written whereami).
+#
+# awk scopes to the section: enter on `## Last updated`, exit on the
+# next `## ` header, emit the first matching date-prefix line, stop.
+# Whereami freshness detection — two tiers per ADR-054 D3 (fallback discipline):
+#   Tier 0 (primary):  state_whereami_get accessor — reads docs/whereami.json
+#                      (migration bootstrap per goal 2026-09-06d Step 3)
+#   Tier 1 (fallback): YAML frontmatter last_updated — handles 3 shapes
+#                      (nested {at, session}, flat scalar, missing field).
+#                      Added 2026-09-05 per bassclef-upstream#1481 diagnose.
+# Legacy `## Last updated` section reader retired per goal 2026-09-06d Cure 3.
+# Adopters mid-migration still fall through dispatcher Try 2 (YAML frontmatter).
+WA_UPDATED=""
+
+# Tier 0 — accessor
+if [ -f "$CWD/lib/state.sh" ]; then
+  # shellcheck source=/dev/null
+  source "$CWD/lib/state.sh" 2>/dev/null && \
+    WA_UPDATED=$(state_whereami_get 2>/dev/null | jq -r '.last_updated.at // empty' 2>/dev/null | cut -dT -f1)
+fi
+
+WHEREAMI="$CWD/docs/whereami.md"
+
+# Tier 1 — YAML frontmatter (nested last_updated.at OR flat scalar last_updated)
+if [ -z "$WA_UPDATED" ] && [ -f "$WHEREAMI" ]; then
+  WA_UPDATED=$(awk '
+    /^---$/ && !in_fm { in_fm=1; next }
+    /^---$/ && in_fm { exit }
+    in_fm && /^last_updated:[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2}/ {
+      match($0, /[0-9]{4}-[0-9]{2}-[0-9]{2}/)
+      print substr($0, RSTART, RLENGTH); exit
+    }
+    in_fm && /^last_updated:[[:space:]]*$/ { nested=1; next }
+    in_fm && nested && /^[[:space:]]+at:[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2}/ {
+      match($0, /[0-9]{4}-[0-9]{2}-[0-9]{2}/)
+      print substr($0, RSTART, RLENGTH); exit
+    }
+    in_fm && nested && /^[a-z_]+:/ { nested=0 }
+  ' "$WHEREAMI" 2>/dev/null)
+fi
+
+if [ -n "$WA_UPDATED" ] && [ "$WA_UPDATED" != "$TODAY" ]; then
+  # Allow yesterday as fresh (just-before-midnight sessions)
+  YESTERDAY=$(date -v-1d +"%Y-%m-%d" 2>/dev/null || date -d 'yesterday' +"%Y-%m-%d" 2>/dev/null || echo "")
+  if [ "$WA_UPDATED" != "$YESTERDAY" ]; then
+    NEEDS_RESCUE=1
+    RESCUE_REASONS="${RESCUE_REASONS}- whereami last_updated is ${WA_UPDATED} (stale, not today/yesterday)\n"
+  fi
+fi
+
+# === Sweep resolved session-rescue entries (bet 2026-07-31e) ===
+#
+# Pair for the write path at L318 below. When all MUST-tier checks
+# passed (NEEDS_RESCUE=0) and rescue entries exist in the active dir,
+# they are the result of prior Stop events whose obligations are now
+# satisfied. Move them to completed/ so the banner reads clean.
+#
+# Deep module hides soft cap, tracked-only check, git-mv, banner. See
+# lib/session-rescue.sh + docs/diagnoses/2026-07-31e-session-rescue-stuck.md.
+if [ "$NEEDS_RESCUE" = "0" ] && [ -f "$CWD/lib/session-rescue.sh" ]; then
+  # shellcheck source=/dev/null
+  source "$CWD/lib/session-rescue.sh" 2>/dev/null && \
+    sweep_resolved_rescue_entries "$CWD" 2>/dev/null || true
+fi
+
+# === Guard 4: active-session SESSION_LOCK check (bassclef#836) ===
+#
+# Suppress rescue-write when another session's SESSION_LOCK is present
+# and fresh. THAT session is still running and will write its own
+# whereami at its own Stop; the current Stop should not pre-emptively
+# write a rescue pointer against the in-progress work.
+#
+# Per bassclef#836 (observed 2026-06-02): rescue fired against
+# whereami last_updated read as stale even though same-session work
+# had updated it ~5h prior. The accessor returned old data; the
+# defensive net here is "if a session is actively running, defer."
+#
+# Held-by-self lock is normal at our own Stop time (save-state.sh
+# clears it at the very end). We only suppress when the lock is held
+# by ANOTHER process group (PGID mismatch).
+if [ "$NEEDS_RESCUE" = "1" ]; then
+  LOCK_FILE_GUARD4="$CWD/.claude/SESSION_LOCK"
+  if [ -f "$LOCK_FILE_GUARD4" ]; then
+    G4_PID=$(grep -E '^pid:' "$LOCK_FILE_GUARD4" 2>/dev/null | head -1 | sed -E 's/^pid:[[:space:]]*//' | tr -d '[:space:]')
+    G4_TS=$(grep -E '^timestamp:' "$LOCK_FILE_GUARD4" 2>/dev/null | head -1 | sed -E 's/^timestamp:[[:space:]]*//')
+    if [ -n "$G4_PID" ] && [ -n "$G4_TS" ]; then
+      G4_PGID=$(ps -o pgid= -p "$G4_PID" 2>/dev/null | tr -d ' ')
+      G4_OUR_PGID=$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')
+      if [ -n "$G4_PGID" ] && [ -n "$G4_OUR_PGID" ] && [ "$G4_PGID" != "$G4_OUR_PGID" ]; then
+        # Held by ANOTHER session — check freshness against TTL
+        G4_LOCK_TTL=${LOCK_TTL_SECONDS:-1800}
+        G4_EPOCH=""
+        if G4_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$G4_TS" +%s 2>/dev/null); then
+          :
+        elif G4_EPOCH=$(date -d "$G4_TS" +%s 2>/dev/null); then
+          :
+        fi
+        if [ -n "$G4_EPOCH" ]; then
+          G4_NOW=$(date +%s)
+          G4_AGE=$((G4_NOW - G4_EPOCH))
+          if [ "$G4_AGE" -lt "$G4_LOCK_TTL" ]; then
+            echo ""
+            echo "============================================"
+            echo "SESSION-RESCUE SUPPRESSED (Guard 4)"
+            echo "============================================"
+            echo ""
+            echo "Another session is actively running (pid $G4_PID, age ${G4_AGE}s)."
+            echo "That session's Stop will write its own whereami; this Stop"
+            echo "skips the rescue write per bassclef#836."
+            NEEDS_RESCUE=""
+          fi
+        fi
+      fi
+    fi
+  fi
+fi
+
+if [ "$NEEDS_RESCUE" = "1" ] && [ -d "$CWD/docs/deferred-actions" ]; then
+  # === Guard 3: write-step dedup (bassclef #260) ===
+  #
+  # #239 closed the dirty-tree self-amplifying loop via Guard 1
+  # (self-output-suppression) and normalized the chronicle check via
+  # Guard 2 (session-relative mtime, not UTC calendar date). A third
+  # path survived both: when chronicle is genuinely missing AND Stop
+  # fires repeatedly before the agent writes it, N firings produce N
+  # identical rescue entries. Observed 2026-04-23: 22 entries in a
+  # 90-min window, all cite `no chronicle written or updated in last
+  # 24h`, payload identical. Filename is timestamped so every firing
+  # creates a fresh path.
+  #
+  # The fix: if an un-resolved rescue entry with mtime < 24h already
+  # exists in the flat directory, skip the write. Payload is
+  # idempotent; one outstanding entry is sufficient signal to the
+  # next session. Multiple entries add redundancy, not safety.
+  #
+  # Multi-session semantics (desktop + mobile ephemeral coexisting,
+  # see PR body for full walkthrough):
+  # - Auto-save (save-state.sh, line 64) runs BEFORE this block on
+  #   every Stop, committing + pushing uncommitted work regardless of
+  #   whether rescue-write is skipped. Work preservation does NOT
+  #   depend on the rescue pointer.
+  # - Dedup is local to $CWD/docs/deferred-actions/. Distinct working
+  #   copies (e.g., desktop clone vs mobile sandbox) each check their
+  #   own tree, so they don't suppress each other's pointers until
+  #   they pull.
+  # - Once they pull, the shared pointer is sufficient: /session-end
+  #   resolves all outstanding rescue entries uniformly (chronicle,
+  #   whereami, tree-clean are shared-file concerns — one fix closes
+  #   N pointers).
+  #
+  # Dedup-skip emits a visible trace block (symmetric with the
+  # rescue-write block below) so stuck-signal diagnostics can detect
+  # pathological cases — e.g., "skipped 200 times in a month" means
+  # /session-end hasn't run in a month and the banner is stuck for a
+  # real reason.
+  EXISTING_RECENT=$(find "$CWD/docs/deferred-actions" -maxdepth 1 -name "*-session-rescue.md" -type f -mtime -1 2>/dev/null | head -1)
+  if [ -n "$EXISTING_RECENT" ]; then
+    echo ""
+    echo "============================================"
+    echo "SESSION-RESCUE ENTRY SKIPPED (dedup)"
+    echo "============================================"
+    echo ""
+    echo "Stop fired with unfinished MUST-tier obligations. An un-"
+    echo "resolved rescue entry already covers them:"
+    echo "  ${EXISTING_RECENT#$CWD/}"
+    echo ""
+    echo "No new entry written. Next session resolves the existing one."
+    echo "If this skip fires repeatedly across many sessions without"
+    echo "resolution, /session-end is the path to clear it."
+    echo "============================================"
+    echo ""
+    exit 0
+  fi
+
+  TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
+  RESCUE_FILE="$CWD/docs/deferred-actions/${TS}-session-rescue.md"
+  cat > "$RESCUE_FILE" <<RESCUE
+---
+id: ${TS}-session-rescue
+created_by_session: session-end-hook-${TS}
+created_in: desktop
+created_at: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+pending_action: resume-unfinished-session
+requires_capability: [git-push, network]
+priority: high
+origin_skill: /session-end
+resolves_when: |
+  MUST-tier session-end obligations listed below are satisfied
+  (chronicle written, whereami current, working tree clean), and
+  this file has been git mv'd to docs/deferred-actions/completed/.
+---
+
+## Context
+
+Stop-hook fired before MUST-tier session-end obligations completed.
+This is the forward-pointer deferred-action entry per bassclef #226
+WS-3 — the next capable session picks up the unfinished work instead
+of silently losing it. Reasons flagged:
+
+$(echo -e "$RESCUE_REASONS")
+
+Common triggers: context exhaustion, OS-level interruption, sandbox
+teardown, agent completed work but didn't run /session-end.
+
+## Command to execute
+
+Next session, run /session-end to complete each flagged obligation in
+order. The skill's procedure enumerates the MUST tier; resolve each
+before moving on. If any flagged obligation turns out to be satisfied
+already (hook false-positive), note it in the resolution entry and
+proceed.
+
+## On completion
+
+- [ ] All flagged obligations resolved
+- [ ] \`git mv "docs/deferred-actions/${TS}-session-rescue.md" "docs/deferred-actions/completed/${TS}-session-rescue.md"\`
+- [ ] \`git commit -m "chore: resolve session-rescue ${TS}"\`
+
+## Cross-refs
+
+- bassclef #231 — WS-3 issue that shipped this pattern
+- bassclef #226 — parent bet
+- \`.claude/rules/session-artifacts.md\`
+- \`.claude/hooks/session-end.sh\` — the hook that wrote this entry
+RESCUE
+  echo ""
+  echo "============================================"
+  echo "SESSION-RESCUE ENTRY WRITTEN"
+  echo "============================================"
+  echo ""
+  echo "Stop fired with unfinished MUST-tier obligations."
+  echo "Forward-pointer entry: ${RESCUE_FILE}"
+  echo ""
+  echo "Next session-start will surface it as BLOCKED:"
+  echo "deferred-action. Resolve per /session-end."
+  echo "============================================"
+  echo ""
+fi
+
+# === Emit session_end telemetry event (bet 2026-07-31f Step 4) ===
+#
+# Silent-fail per @luminary michael-nygard R1 — never crashes Stop.
+# Only fires when adopter has opted in via lib/telemetry.sh enable.
+{
+  if [ -f "$CWD/lib/telemetry.sh" ]; then
+    # shellcheck source=/dev/null
+    source "$CWD/lib/telemetry.sh" 2>/dev/null
+    if telemetry_is_enabled 2>/dev/null; then
+      _sid=$(telemetry_session_id 2>/dev/null)
+      _uid=$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' || echo "00000000-0000-4000-8000-000000000003")
+      _ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+      telemetry_emit "{\"event_type\":\"session_end\",\"event_id\":\"$_uid\",\"session_id\":\"$_sid\",\"timestamp\":\"$_ts\",\"tier\":\"lite\",\"payload\":{}}" 2>/dev/null
+      telemetry_reset_session 2>/dev/null
+    fi
+  fi
+} 2>/dev/null || true
+
+exit 0