uv-suite 0.27.0 → 0.29.0

package/hooks/auto-restore-on-start.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# UV Suite Hook: SessionStart — when UVS_RESTORE_FROM is set, inject a
+# system-context instruction telling Claude to /restore that session as
+# the first action of the new session.
+#
+# This is how the Watchtower's "Open in new terminal" restore button hooks
+# back into the new uvs session — the env var is set by the spawned terminal
+# command, propagates through uvs/claude, and lands here.
+
+if [ -z "$UVS_RESTORE_FROM" ]; then
+  exit 0
+fi
+
+# Sanity check — sid must look like a UUID prefix or our ad-hoc-<ts>
+case "$UVS_RESTORE_FROM" in
+  [a-zA-Z0-9-]*) : ;;
+  *)
+    echo "[auto-restore] ignoring malformed UVS_RESTORE_FROM" >&2
+    exit 0
+    ;;
+esac
+
+MSG="[uv-suite auto-restore] This session was opened via the Watchtower restore flow. Your FIRST action must be to run \`/restore $UVS_RESTORE_FROM\` to load the prior session's latest checkpoint. After /restore completes, summarize what you picked up in 1-2 sentences, then wait for the user's next instruction."
+
+if command -v jq >/dev/null 2>&1; then
+  jq -nc --arg ctx "$MSG" '{hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:$ctx}}'
+else
+  ESCAPED=$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}' "$ESCAPED"
+fi

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.29.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/personas/auto.json

@@ -70,6 +70,11 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh SessionStart",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-restore-on-start.sh",
+            "timeout": 3
           }
         ]
       }

package/personas/professional.json

@@ -70,6 +70,11 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh SessionStart",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-restore-on-start.sh",
+            "timeout": 3
           }
         ]
       }

package/personas/spike.json

@@ -63,6 +63,11 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh SessionStart",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-restore-on-start.sh",
+            "timeout": 3
           }
         ]
       }

package/personas/sport.json

@@ -52,6 +52,11 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh SessionStart",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-restore-on-start.sh",
+            "timeout": 3
           }
         ]
       }

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);