uv-suite 0.27.0 → 0.28.0

package/hooks/session-end-helper.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# UV Suite helper: explicit session termination.
+# Used by the /session-end slash command.
+#
+# Writes a "terminated_at" timestamp to the session metadata, fires a
+# SessionEnd event to the Watchtower so the dashboard updates the status
+# badge, and prints a one-line confirmation.
+
+STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.uv-suite-state"
+SESSIONS_DIR="$STATE_DIR/sessions"
+mkdir -p "$SESSIONS_DIR"
+
+SID="${UVS_SESSION_ID:-}"
+if [ -z "$SID" ] && [ -f "$STATE_DIR/current-session.txt" ]; then
+  SID=$(cat "$STATE_DIR/current-session.txt" 2>/dev/null)
+fi
+
+if [ -z "$SID" ]; then
+  echo "No active UV Suite session to end."
+  exit 1
+fi
+
+META="$SESSIONS_DIR/$SID.json"
+NOW=$(date +%s)
+NOW_ISO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+if [ -f "$META" ]; then
+  META_PATH="$META" NOW_VAL="$NOW" NOW_ISO_VAL="$NOW_ISO" python3 - <<'PY'
+import json, os
+p = os.environ["META_PATH"]
+d = json.load(open(p))
+d["terminated_at"] = int(os.environ["NOW_VAL"])
+d["terminated_at_iso"] = os.environ["NOW_ISO_VAL"]
+d["lifecycle"] = "terminated"
+json.dump(d, open(p, "w"), indent=2)
+PY
+fi
+
+# Fire SessionEnd event so the dashboard flips the status badge to Terminated.
+if [ -x "$CLAUDE_PROJECT_DIR/.claude/hooks/watchtower-send.sh" ]; then
+  PAYLOAD=$(SID_VAL="$SID" NOW_VAL="$NOW" CWD_VAL="${CLAUDE_PROJECT_DIR:-$(pwd)}" python3 -c '
+import json, os
+print(json.dumps({
+    "uvs_session_id": os.environ["SID_VAL"],
+    "session_id": os.environ["SID_VAL"],
+    "cwd": os.environ["CWD_VAL"],
+    "lifecycle": "terminated",
+    "terminated_at": int(os.environ["NOW_VAL"]),
+    "terminated_by": "user",
+}))
+')
+  printf '%s' "$PAYLOAD" | "$CLAUDE_PROJECT_DIR/.claude/hooks/watchtower-send.sh" SessionEnd 2>/dev/null
+fi
+
+echo "Session ${SID:0:8} marked terminated at $NOW_ISO."
+echo "Run /checkpoint first if you want a final state snapshot, then exit the terminal."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Portable framework for AI-assisted software development. 10 agents, 9 skills, 5 hooks, 4 personas. Works with Claude Code, Cursor, and Codex.",
   "author": "Utsav Anand",
   "license": "MIT",

package/skills/session-end/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: session-end
+description: >
+  Cleanly close the current UV Suite session: write a final manual checkpoint
+  (full conversation context), then mark the session as terminated so the
+  Watchtower dashboard flips its lifecycle badge to Terminated. Use before
+  closing the terminal when you want a deliberate end-of-session beat.
+argument-hint: "[optional-label]"
+user-invocable: true
+allowed-tools:
+  - Write(*)
+  - Read(*)
+  - Bash(git status *)
+  - Bash(git diff *)
+  - Bash(git log *)
+  - Bash(git branch *)
+  - Bash(git rev-parse *)
+  - Bash(date *)
+  - Bash(ls *)
+  - Bash(mkdir *)
+  - Bash(cat *)
+  - Bash(echo *)
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh *)
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/session-end-helper.sh *)
+---
+
+## Resolve checkpoint directory + session metadata
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh dir`
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh frontmatter`
+
+## Git state
+
+!`git branch --show-current 2>/dev/null || echo "(not a git repo)"`
+
+!`git status --short 2>/dev/null | head -20 || echo "(no git)"`
+
+!`git log --oneline -5 2>/dev/null || echo "(no git history)"`
+
+## Step 1 — Write the final checkpoint
+
+Write a file at `<checkpoint-dir>/final-YYYY-MM-DD-HHMM.md` using the current
+timestamp. **Override** the frontmatter line `checkpoint_kind: auto-mechanical`
+to read `checkpoint_kind: final-manual` so it's distinguishable from the
+auto-checkpoints. Also write/overwrite `<checkpoint-dir>/latest.md` with the
+same content so `/restore` picks it up.
+
+If a label was provided, include it in the filename:
+`<checkpoint-dir>/final-YYYY-MM-DD-HHMM-[label].md`
+
+### Label
+
+$ARGUMENTS
+
+### Body structure (after the frontmatter)
+
+```markdown
+# Final checkpoint: [date] [time] [label if provided]
+
+## What was accomplished
+- Concrete things done across the whole session — files, commits, decisions
+- One bullet per significant artifact; don't pad
+
+## Key decisions made
+- Decision: Why — what was considered, what was rejected
+
+## Current state
+- Branch / uncommitted changes / tests status / blockers
+
+## Open threads
+- Anything left in flight that the next session needs to pick up
+- Pending reviews, awaiting input, deferred work
+
+## Context the next session needs
+- Non-obvious facts, workarounds, "this looks wrong but it's intentional because…"
+```
+
+Be specific. This is the last record before the session closes — anything
+not written here is lost unless it's in code or the auto-checkpoints.
+
+## Step 2 — Mark the session terminated
+
+Once the file is written, run:
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/session-end-helper.sh`
+
+Show the user the two-line output. Don't add commentary — the file write
+and the termination signal together speak for themselves.
+
+## Notes
+
+- `/session-end` does **not** close the terminal or exit Claude Code. After
+  it runs, the badge flips to Terminated in the Watchtower; the user
+  closes the terminal manually.
+- The final checkpoint uses the live session's full conversation context —
+  higher fidelity than the auto-checkpoint summaries because Claude has
+  everything in working memory at this moment.
+- If you only want to terminate without a checkpoint, run
+  `hooks/session-end-helper.sh` directly from bash and skip this skill.

package/watchtower/auto-checkpoint-prompt.md

@@ -1,6 +1,6 @@
-You are writing an auto-checkpoint for a UV Suite coding session. Be specific
-and tight — this is a state snapshot, not a narrative. Don't speculate beyond
-what the events show.
+You are writing a one-paragraph summary for the UV Suite auto-checkpoint
+system. The actual conversation transcript is provided below — base the
+summary on what was actually said and done, not on inference.
 
 ## Session
 
@@ -11,41 +11,32 @@ what the events show.
 - purpose: {{purpose}}
 - elapsed since last semantic checkpoint: {{elapsed_min}} min
 
-## Activity (last {{interval_min}} min, from the dashboard)
+## Conversation (verbatim, last {{interval_min}} min)
 
-{{event_list}}
+{{conversation}}
 
-## Git
-
-```
-{{git_branch}}
-{{git_status}}
-{{git_log}}
-```
+## Mechanical (from the dashboard event log)
 
-## Write the checkpoint
+{{mechanical}}
 
-Output **only** the markdown body below — no preamble, no closing remarks.
-Use this exact shape, max 30 lines total:
-
-```markdown
-# Auto-checkpoint: {{timestamp}}
+## Git
 
-## Done in the last {{interval_min}} min
-- 2-4 bullets — concrete: file edited, command run, decision visible in events.
-  Skip vague verbs ("worked on"); name the artifact and the change.
+Branch: {{git_branch}}
+Status: {{git_status}}
+Recent commits: {{git_log}}
 
-## Files touched
-- list (omit section if empty)
+## Write the summary
 
-## In progress
-- 1-2 bullets — what the session appears to be working on right now, based
-  on the latest events.
+Output **only** a single paragraph, 3-6 sentences, no headers, no bullets.
+The paragraph should answer, in order:
 
-## Notable
-- only include this section if something stands out (a failure, a long pause
-  followed by a burst, a clear pattern shift). Otherwise omit the section.
-```
+1. What was the user trying to do this window?
+2. What did Claude actually do — concrete files / commands / decisions?
+3. Where does the session stand right now (in progress / blocked / awaiting input)?
 
-If the activity log is sparse or ambiguous, say so plainly in "In progress"
-rather than inventing details.
+Rules:
+- Use the user's own words for the topic when possible ("user asked about X")
+- Name the artifacts (file paths, command names, function names) — no vague verbs
+- If the conversation is sparse, say "Quiet window — only X tool calls, no
+  substantive exchange" and stop. Don't invent activity.
+- Don't restate the session metadata; it's already in the frontmatter.

package/watchtower/auto-checkpoint-runner.js

@@ -1,17 +1,30 @@
 // UV Suite — Tier B auto-checkpoint runner.
 // Called from watchtower/server.js on a setInterval. For each active session
-// (one with at least one event in the last interval), shells out to
-// `claude -p --bare --model haiku` to write a semantic summary.
+// whose interval has elapsed, reads the Claude Code transcript JSONL at
+// ~/.claude/projects/<encoded-cwd>/<session_id>.jsonl, extracts the
+// conversation in the window, and writes a self-contained checkpoint:
+//
+//   ## Summary       — one paragraph from `claude -p --bare --model haiku`
+//                      using the transcript as input
+//   ## Conversation  — raw extract: user prompts verbatim + assistant
+//                      response openings (~250 chars each) + tool calls
+//   ## Mechanical    — git state + tool counts + files touched
+//
+// The transcript is copied into our checkpoint, so the file stands alone
+// even if Claude Code later deletes its source JSONL.
 
 const fs = require("fs");
 const path = require("path");
+const os = require("os");
 const { spawn } = require("child_process");
 
 const PROMPT_TEMPLATE_PATH = path.join(__dirname, "auto-checkpoint-prompt.md");
 const DEFAULT_INTERVAL_MIN = 10;
-const POLL_INTERVAL_MS = 60 * 1000; // wake up every 60s; per-session cadence is honored individually
+const POLL_INTERVAL_MS = 60 * 1000;
 const MAX_BUDGET_USD = "0.05";
 const MODEL = "haiku";
+const MAX_ASSISTANT_PREVIEW_CHARS = 250;
+const MAX_CONVERSATION_LINES = 200;
 
 function readJsonSafe(p) {
   try {
@@ -64,6 +77,136 @@ function groupActiveSessions(events, windowMs) {
   return [...bySession.values()];
 }
 
+// Claude Code stores transcripts at ~/.claude/projects/<encoded>/<sid>.jsonl
+// where <encoded> is the project path with "/" replaced by "-".
+function transcriptPathFor(cwd, ccSessionId) {
+  if (!ccSessionId) return null;
+  const encoded = cwd.replace(/\//g, "-");
+  return path.join(
+    os.homedir(),
+    ".claude",
+    "projects",
+    encoded,
+    `${ccSessionId}.jsonl`,
+  );
+}
+
+// Defensive parser: Claude Code's JSONL format is internal and may change.
+// We pull out user prompts, assistant responses, and tool calls — skipping
+// anything we can't interpret rather than blowing up.
+function extractTextFromContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => {
+        if (typeof block === "string") return block;
+        if (block && block.type === "text" && typeof block.text === "string")
+          return block.text;
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  return "";
+}
+
+// Read transcript messages whose timestamp falls in [sinceMs, +inf).
+// Returns a flat array of { role, text, ts, tool? } records, oldest first.
+function readTranscriptMessages(transcriptPath, sinceMs) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    if (transcriptPath) {
+      console.warn(`[auto-checkpoint] transcript not found: ${transcriptPath}`);
+    }
+    return null;
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, "utf-8");
+  } catch (err) {
+    console.warn(`[auto-checkpoint] failed to read transcript: ${err.message}`);
+    return null;
+  }
+  const out = [];
+  let totalLines = 0;
+  let parseFailures = 0;
+  let recognizedShapes = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    totalLines++;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      parseFailures++;
+      continue;
+    }
+    const tsStr = msg.timestamp || msg.ts || msg.createdAt || msg.created_at;
+    const ts = tsStr ? Date.parse(tsStr) : NaN;
+    if (Number.isFinite(ts) && ts < sinceMs) continue;
+
+    // Tolerate several shapes Claude Code has used:
+    //   { type: "user"|"assistant", message: { role, content } }
+    //   { role, content }
+    //   { sender: "user"|"assistant", text }                  (older)
+    //   { event: "message", role, content }                   (variant)
+    const role =
+      msg.role ||
+      msg.message?.role ||
+      msg.sender ||
+      (msg.type === "user" || msg.type === "assistant" ? msg.type : null);
+    const content = msg.message?.content ?? msg.content ?? msg.text ?? msg.body;
+    const text = extractTextFromContent(content).trim();
+
+    if (role === "user" && text) {
+      out.push({ role: "user", text, ts });
+      recognizedShapes++;
+    } else if (role === "assistant" && text) {
+      out.push({ role: "assistant", text, ts });
+      recognizedShapes++;
+    }
+  }
+  // Surface format drift loudly: if the file has content but nothing parsed
+  // as a recognizable message, the Claude Code schema has probably changed.
+  if (totalLines > 0 && recognizedShapes === 0) {
+    console.warn(
+      `[auto-checkpoint] transcript at ${transcriptPath}: ${totalLines} lines, ` +
+        `${parseFailures} JSON-parse failures, 0 recognized user/assistant messages. ` +
+        `Claude Code's transcript format may have changed — please file an issue.`,
+    );
+  }
+  return out;
+}
+
+// Build the ## Conversation extract markdown block. Trims long assistant
+// turns; caps total lines.
+function buildConversationExtract(messages) {
+  if (!messages || messages.length === 0) return "";
+  const lines = [];
+  for (const m of messages) {
+    if (m.role === "user") {
+      lines.push(`**You:**`);
+      for (const ln of m.text.split("\n")) lines.push(`> ${ln}`);
+    } else {
+      let preview = m.text;
+      if (preview.length > MAX_ASSISTANT_PREVIEW_CHARS) {
+        preview =
+          preview.slice(0, MAX_ASSISTANT_PREVIEW_CHARS).trimEnd() + " …";
+      }
+      lines.push(`**Claude:** ${preview.replace(/\n+/g, " ")}`);
+    }
+    lines.push("");
+  }
+  if (lines.length > MAX_CONVERSATION_LINES) {
+    const trimmed = lines.slice(-MAX_CONVERSATION_LINES);
+    trimmed.unshift(
+      `_(earlier turns truncated; showing last ${MAX_CONVERSATION_LINES} lines)_`,
+      "",
+    );
+    return trimmed.join("\n");
+  }
+  return lines.join("\n");
+}
+
 function eventToCompactLine(ev) {
   const t = ev.event_type || ev.hook_event_name || "?";
   const tool = ev.tool_name || "";
@@ -170,41 +313,94 @@ async function processSession(session, broadcast) {
     .sort((a, b) => (a._ts || 0) - (b._ts || 0));
   if (recent.length === 0) return;
 
-  const template = loadPromptTemplate();
-  if (!template) {
-    console.warn("[auto-checkpoint] prompt template missing; skipping");
-    return;
+  // Find the Claude Code session id from the most recent event (it differs
+  // from uvs_session_id) and read the conversation transcript.
+  const ccSessionId =
+    [...recent].reverse().find((e) => e.session_id)?.session_id || null;
+  const transcriptPath = transcriptPathFor(cwd, ccSessionId);
+  const sinceMs = lastTs > 0 ? lastTs * 1000 : now - intervalMs;
+  const transcriptMessages = readTranscriptMessages(transcriptPath, sinceMs);
+
+  const conversationExtract =
+    buildConversationExtract(transcriptMessages) ||
+    "_(no transcript content found; only mechanical activity captured below)_";
+
+  // Mechanical breakdown — tool counts and files touched.
+  const toolCounts = {};
+  const fileCounts = {};
+  for (const e of recent) {
+    const t = e.tool_name;
+    if (t) toolCounts[t] = (toolCounts[t] || 0) + 1;
+    const fp = e.tool_input?.file_path;
+    if (fp && (t === "Edit" || t === "Write" || t === "Read")) {
+      fileCounts[fp] = (fileCounts[fp] || 0) + 1;
+    }
+  }
+  const mechanicalLines = [];
+  mechanicalLines.push("### Tool calls");
+  Object.entries(toolCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 8)
+    .forEach(([t, n]) => mechanicalLines.push(`- ${n}× ${t}`));
+  if (Object.keys(fileCounts).length) {
+    mechanicalLines.push("", "### Files touched");
+    Object.entries(fileCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 8)
+      .forEach(([f, n]) => mechanicalLines.push(`- ${f} (${n})`));
   }
+  const mechanicalBlock = mechanicalLines.join("\n");
 
   const git = await gitState(cwd);
-  const eventList = recent.slice(-40).map(eventToCompactLine).join("\n");
-  const elapsedMin =
-    lastTs === 0
-      ? state.interval_minutes
-      : Math.round((now - lastTs * 1000) / 60000);
-
-  const prompt = buildPrompt(template, {
-    name: session.session_name || "(unset)",
-    kind: session.session_kind || "(unset)",
-    priority: session.session_priority || "(unset)",
-    persona: session.persona || "(unset)",
-    purpose: session.session_purpose || "(unset)",
-    elapsed_min: String(elapsedMin),
-    interval_min: String(state.interval_minutes),
-    event_list: eventList,
-    git_branch: git.branch ? `Branch: ${git.branch}` : "(not a git repo)",
-    git_status: git.status || "(no changes)",
-    git_log: git.log || "",
-    timestamp: new Date(now).toISOString(),
-  });
+  const gitBlock = [
+    git.branch ? `**Branch:** ${git.branch}` : "_(not a git repo)_",
+    git.status
+      ? "**Status:**\n```\n" + git.status + "\n```"
+      : "**Status:** clean",
+    git.log ? "**Recent commits:**\n```\n" + git.log + "\n```" : "",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
 
-  const result = await runClaudeP(prompt);
-  if (!result.ok || !result.stdout.trim()) {
-    console.warn(
-      `[auto-checkpoint] claude -p failed for ${sid.slice(0, 8)}:`,
-      result.error || result.stderr?.slice(0, 200) || `exit ${result.code}`,
-    );
-    return;
+  // Summary via claude -p, fed the actual conversation extract instead of
+  // just the event log. Falls back to a one-line stub if the call fails or
+  // the transcript is empty.
+  let summary = "";
+  const template = loadPromptTemplate();
+  if (template && transcriptMessages && transcriptMessages.length > 0) {
+    const elapsedMin =
+      lastTs === 0
+        ? state.interval_minutes
+        : Math.round((now - lastTs * 1000) / 60000);
+    const prompt = buildPrompt(template, {
+      name: session.session_name || "(unset)",
+      kind: session.session_kind || "(unset)",
+      priority: session.session_priority || "(unset)",
+      persona: session.persona || "(unset)",
+      purpose: session.session_purpose || "(unset)",
+      elapsed_min: String(elapsedMin),
+      interval_min: String(state.interval_minutes),
+      conversation: conversationExtract,
+      mechanical: mechanicalBlock,
+      git_branch: git.branch || "(not a git repo)",
+      git_status: git.status || "(no changes)",
+      git_log: git.log || "",
+      timestamp: new Date(now).toISOString(),
+    });
+    const result = await runClaudeP(prompt);
+    if (result.ok && result.stdout.trim()) {
+      summary = result.stdout.trim();
+    } else {
+      console.warn(
+        `[auto-checkpoint] summary call failed for ${sid.slice(0, 8)}:`,
+        result.error || result.stderr?.slice(0, 200) || `exit ${result.code}`,
+      );
+    }
+  }
+  if (!summary) {
+    summary = transcriptMessages
+      ? "_(summary generation failed; raw conversation below)_"
+      : "_(no conversation transcript available; only mechanical activity below)_";
   }
 
   // Write the checkpoint file
@@ -227,15 +423,37 @@ async function processSession(session, broadcast) {
     `persona: ${session.persona || ""}`,
     `checkpoint_at: ${new Date(now).toISOString()}`,
     `checkpoint_kind: auto-semantic`,
+    `transcript_messages: ${transcriptMessages ? transcriptMessages.length : 0}`,
+    `tool_calls_in_window: ${recent.length}`,
     "---",
     "",
   ].join("\n");
 
-  fs.writeFileSync(cpFile, frontmatter + result.stdout.trim() + "\n");
+  const body = [
+    `# Auto-checkpoint (semantic): ${new Date(now).toISOString()}`,
+    "",
+    "## Summary",
+    "",
+    summary,
+    "",
+    "## Conversation",
+    "",
+    conversationExtract,
+    "",
+    "## Mechanical",
+    "",
+    mechanicalBlock,
+    "",
+    "## Git",
+    "",
+    gitBlock,
+    "",
+  ].join("\n");
+
+  fs.writeFileSync(cpFile, frontmatter + body);
   fs.writeFileSync(lastFile, String(Math.floor(now / 1000)));
 
-  // Broadcast as AutoCheckpoint event
-  const preview = (frontmatter + result.stdout).slice(0, 2000);
+  // Broadcast — the dashboard's expand-on-click body uses the summary.
   const event = {
     event_type: "AutoCheckpoint",
     source_app: path.basename(cwd),
@@ -248,9 +466,11 @@ async function processSession(session, broadcast) {
     persona: session.persona,
     checkpoint_kind: "auto-semantic",
     checkpoint_path: cpFile,
-    checkpoint_preview: preview,
+    checkpoint_summary: summary,
+    checkpoint_preview: (frontmatter + body).slice(0, 2000),
     interval_minutes: state.interval_minutes,
     tool_calls_in_window: recent.length,
+    transcript_messages: transcriptMessages ? transcriptMessages.length : 0,
     _ts: now,
   };
   broadcast(event);

package/watchtower/dashboard.html

@@ -305,7 +305,12 @@
   .pill.priority-high { background: rgba(255, 69, 58, 0.18);   color: var(--danger); }
   .pill.kind-long-running { background: rgba(100, 210, 255, 0.18); color: var(--info); }
   .pill.kind-outcome      { background: rgba(255, 105, 97, 0.18);  color: var(--peach); }
+  .pill.lifecycle-active     { background: rgba(48, 209, 88, 0.18);  color: var(--success); }
+  .pill.lifecycle-idle       { background: rgba(154, 154, 163, 0.18); color: var(--text-muted); }
+  .pill.lifecycle-terminated { background: rgba(255, 69, 58, 0.16);   color: var(--danger); }
 
+  .session-tag.lifecycle-terminated { opacity: 0.55; }
+  .session-tag.lifecycle-terminated strong { text-decoration: line-through; }
   .session-tag.priority-low  { opacity: 0.6; }
   .session-tag .meta-line {
     display: block;
@@ -487,9 +492,10 @@ function sessionColor(id) {
   if (!sessions[id]) {
     sessions[id] = {
       color: palette[colorIdx++ % palette.length],
-      count: 0, lastEvent: null,
+      count: 0, lastEvent: null, lastEventTs: 0,
       name: '', kind: '', purpose: '', priority: '', persona: '',
       app: null, label: null,
+      terminated: false, terminatedAt: 0,
     };
     updateSessionBar();
     updateFilterSession();
@@ -505,6 +511,7 @@ function updateSessionLabel(sid, ev) {
   let changed = false;
 
   if (!s.app && ev.source_app) { s.app = ev.source_app; changed = true; }
+  if (ev._ts && ev._ts > (s.lastEventTs || 0)) s.lastEventTs = ev._ts;
 
   // Configured metadata wins over heuristics. Update on every event so a
   // mid-session /session-init relabel is reflected without a refresh.
@@ -519,8 +526,17 @@ function updateSessionLabel(sid, ev) {
     }
   }
 
-  // Fall back to first UserPromptSubmit if no configured name yet
+  // Lifecycle: a session is Terminated when we receive Stop / SessionEnd
+  // (Claude Code's natural exit signal) OR when ev.lifecycle === 'terminated'
+  // (the /session-end slash command). Time-idleness alone does NOT terminate.
   const type = ev.event_type || ev.hook_event_name || '';
+  if (!s.terminated && (type === 'Stop' || type === 'SessionEnd' || ev.lifecycle === 'terminated')) {
+    s.terminated = true;
+    s.terminatedAt = ev._ts || Date.now();
+    changed = true;
+  }
+
+  // Fall back to first UserPromptSubmit if no configured name yet
   if (!s.name && !s.label && type === 'UserPromptSubmit') {
     const prompt = ev.tool_input?.prompt || ev.tool_input?.content || ev.message || '';
     if (prompt.length > 0) {
@@ -537,6 +553,16 @@ function updateSessionLabel(sid, ev) {
   }
 }
 
+// Active = event in last ACTIVE_WINDOW_MS; Terminated = explicit signal seen;
+// Idle = anything else (including long-running sessions sitting dormant).
+const ACTIVE_WINDOW_MS = 5 * 60 * 1000;
+function sessionStatus(s) {
+  if (!s) return 'idle';
+  if (s.terminated) return 'terminated';
+  if ((Date.now() - (s.lastEventTs || 0)) <= ACTIVE_WINDOW_MS) return 'active';
+  return 'idle';
+}
+
 function sessionDisplayName(id) {
   const s = sessions[id];
   if (!s) return shortId(id);
@@ -744,6 +770,10 @@ setInterval(() => {
   if (events.length > 0) updateWaitingText(events[events.length - 1]);
 }, 5000);
 
+// Refresh the session bar periodically so Active→Idle transitions show up
+// without requiring a new event to arrive.
+setInterval(updateSessionBar, 30000);
+
 function updateStats() {
   document.getElementById('sessionCount').textContent = Object.keys(sessions).length;
   document.getElementById('eventCount').textContent = events.length;
@@ -771,11 +801,18 @@ function pill(cls, label) {
   return `<span class="pill ${cls}">${escapeHtml(label)}</span>`;
 }
 
+// Lifecycle sort: active first, then idle, terminated last.
+const LIFECYCLE_ORDER = { active: 0, idle: 1, terminated: 2 };
+
 function updateSessionBar() {
   sessionBar.innerHTML = '';
-  // Sort: high priority first, then med/unset, then low; within a tier, most
-  // recent activity wins so the dashboard surfaces what's happening now.
+  // Sort: lifecycle (active → idle → terminated) trumps priority (high → low),
+  // then most-recent activity. So a high-priority terminated session sits
+  // below a low-priority active one — what's running now matters more.
   const ids = Object.keys(sessions).sort((a, b) => {
+    const la = LIFECYCLE_ORDER[sessionStatus(sessions[a])];
+    const lb = LIFECYCLE_ORDER[sessionStatus(sessions[b])];
+    if (la !== lb) return la - lb;
     const pa = PRIORITY_ORDER[sessions[a].priority] ?? PRIORITY_ORDER[''];
     const pb = PRIORITY_ORDER[sessions[b].priority] ?? PRIORITY_ORDER[''];
     if (pa !== pb) return pa - pb;
@@ -784,16 +821,19 @@ function updateSessionBar() {
 
   for (const id of ids) {
     const s = sessions[id];
+    const lifecycle = sessionStatus(s);
     const tag = document.createElement('span');
     let cls = 'session-tag';
     if (selectedSession === id) cls += ' active';
     if (s.priority === 'low')   cls += ' priority-low';
+    cls += ' lifecycle-' + lifecycle;
     tag.className = cls;
     tag.style.background = s.color + '22';
     tag.style.color = s.color;
     tag.title = `${id}${s.purpose ? '\n' + s.purpose : ''}`;
 
     const pills = [];
+    pills.push(pill('lifecycle-' + lifecycle, lifecycle));
     if (s.persona)  pills.push(pill('persona-' + s.persona, s.persona));
     if (s.priority) pills.push(pill('priority-' + s.priority, 'P:' + s.priority));
     if (s.kind)     pills.push(pill('kind-' + s.kind, s.kind));