uv-suite 0.26.5 → 0.27.0

package/hooks/auto-checkpoint-helper.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# UV Suite helper: read or change auto-checkpoint settings.
+# Used by the /auto-checkpoint slash command.
+#
+# Usage:
+#   auto-checkpoint-helper.sh status
+#   auto-checkpoint-helper.sh on
+#   auto-checkpoint-helper.sh off
+#   auto-checkpoint-helper.sh <minutes>     # set interval
+
+STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.uv-suite-state"
+mkdir -p "$STATE_DIR"
+STATE_FILE="$STATE_DIR/auto-checkpoint.json"
+
+ensure_state() {
+  [ -f "$STATE_FILE" ] && return
+  cat > "$STATE_FILE" <<'EOF'
+{
+  "mode": "on",
+  "interval_minutes": 10
+}
+EOF
+}
+
+get_field() {
+  ensure_state
+  STATE_PATH="$STATE_FILE" KEY="$1" python3 -c '
+import json, os
+d = json.load(open(os.environ["STATE_PATH"]))
+print(d.get(os.environ["KEY"], ""))
+'
+}
+
+set_field() {
+  ensure_state
+  STATE_PATH="$STATE_FILE" KEY="$1" VAL="$2" python3 -c '
+import json, os
+p = os.environ["STATE_PATH"]
+d = json.load(open(p))
+key = os.environ["KEY"]
+val = os.environ["VAL"]
+if key == "interval_minutes":
+    val = int(val)
+d[key] = val
+json.dump(d, open(p, "w"), indent=2)
+'
+}
+
+ARG=$(printf '%s' "$1" | tr -d '[:space:]')
+
+case "$ARG" in
+  on)
+    set_field mode on
+    echo "Auto-checkpoint: ON (every $(get_field interval_minutes) min, mechanical + semantic)"
+    ;;
+  off)
+    set_field mode off
+    echo "Auto-checkpoint: OFF"
+    ;;
+  ""|status)
+    ensure_state
+    echo "Auto-checkpoint: $(get_field mode) (every $(get_field interval_minutes) min)"
+    ;;
+  *)
+    if printf '%s' "$ARG" | grep -qE '^[0-9]+$' && [ "$ARG" -ge 1 ] && [ "$ARG" -le 1440 ]; then
+      set_field interval_minutes "$ARG"
+      echo "Auto-checkpoint interval: $ARG min (mode: $(get_field mode))"
+    else
+      echo "Usage: /auto-checkpoint [on | off | <minutes 1-1440> | status]"
+      exit 1
+    fi
+    ;;
+esac

package/hooks/auto-checkpoint.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+# UV Suite Hook: Tier A auto-checkpoint — mechanical state snapshot.
+# Event: PostToolUse
+#
+# Logs every tool call into a per-session activity log. When `interval_minutes`
+# have passed since the last mechanical checkpoint AND there has been activity
+# in the interval, writes a deterministic snapshot to
+# uv-out/checkpoints/<sid>/auto-<ts>-mechanical.md and forwards an
+# AutoCheckpoint event to the watchtower.
+#
+# Tier B (semantic, claude -p) runs separately from the watchtower's timer.
+
+INPUT=$(cat 2>/dev/null || true)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+STATE_DIR="$PROJECT_DIR/.uv-suite-state"
+SESSIONS_DIR="$STATE_DIR/sessions"
+mkdir -p "$SESSIONS_DIR" 2>/dev/null
+
+STATE_FILE="$STATE_DIR/auto-checkpoint.json"
+
+# Default state if missing
+if [ ! -f "$STATE_FILE" ]; then
+  cat > "$STATE_FILE" <<'EOF'
+{
+  "mode": "on",
+  "interval_minutes": 10
+}
+EOF
+fi
+
+# Read mode + interval (skip if mode != on)
+read_state() {
+  STATE_PATH="$STATE_FILE" python3 -c '
+import json, os, sys
+try:
+    d = json.load(open(os.environ["STATE_PATH"]))
+    print(d.get("mode", "on"))
+    print(d.get("interval_minutes", 10))
+except Exception:
+    print("on"); print("10")
+' 2>/dev/null
+}
+
+STATE_OUT=$(read_state)
+MODE=$(echo "$STATE_OUT" | sed -n 1p)
+INTERVAL_MIN=$(echo "$STATE_OUT" | sed -n 2p)
+[ "$MODE" != "on" ] && exit 0
+[ -z "$INTERVAL_MIN" ] && INTERVAL_MIN=10
+
+# Resolve session id
+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
+[ -z "$SID" ] && exit 0
+
+ACTIVITY_LOG="$SESSIONS_DIR/$SID.activity.log"
+LAST_CP_FILE="$SESSIONS_DIR/$SID.last-mechanical-checkpoint.txt"
+NOW=$(date +%s)
+
+# Append activity entry. Cap log at last 500 lines.
+TOOL=""
+TARGET=""
+if command -v jq >/dev/null 2>&1; then
+  TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+  TARGET=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.command // .tool_input.pattern // .tool_input.url // ""' 2>/dev/null)
+fi
+TARGET=$(printf '%s' "$TARGET" | tr -d '\n' | cut -c1-120)
+[ -n "$TOOL" ] && echo "$NOW $TOOL $TARGET" >> "$ACTIVITY_LOG"
+if [ -f "$ACTIVITY_LOG" ]; then
+  LINES=$(wc -l < "$ACTIVITY_LOG" 2>/dev/null | tr -d ' ')
+  if [ -n "$LINES" ] && [ "$LINES" -gt 500 ]; then
+    tail -n 500 "$ACTIVITY_LOG" > "$ACTIVITY_LOG.tmp" && mv "$ACTIVITY_LOG.tmp" "$ACTIVITY_LOG"
+  fi
+fi
+
+# Has the interval passed since last mechanical checkpoint?
+# On the very first run, seed the timestamp with NOW so we don't fire a
+# checkpoint immediately — the first one fires after the interval has elapsed.
+if [ ! -f "$LAST_CP_FILE" ]; then
+  echo "$NOW" > "$LAST_CP_FILE"
+  exit 0
+fi
+LAST_CP=$(cat "$LAST_CP_FILE" 2>/dev/null)
+LAST_CP=${LAST_CP:-0}
+ELAPSED=$((NOW - LAST_CP))
+INTERVAL_SEC=$((INTERVAL_MIN * 60))
+[ "$ELAPSED" -lt "$INTERVAL_SEC" ] && exit 0
+
+# Activity since last checkpoint? If none, skip.
+SINCE_LINES=0
+if [ -f "$ACTIVITY_LOG" ]; then
+  SINCE_LINES=$(awk -v cutoff="$LAST_CP" '$1 > cutoff' "$ACTIVITY_LOG" 2>/dev/null | wc -l | tr -d ' ')
+fi
+[ "${SINCE_LINES:-0}" -lt 1 ] && exit 0
+
+# Resolve checkpoint dir + metadata via the existing helper
+CP_DIR=$(CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$PROJECT_DIR/.claude/hooks/checkpoint-helper.sh" dir 2>/dev/null)
+[ -z "$CP_DIR" ] && CP_DIR="$PROJECT_DIR/uv-out/checkpoints/$SID" && mkdir -p "$CP_DIR"
+
+# Build the mechanical checkpoint body
+TS_FILE=$(date +%Y-%m-%d-%H%M)
+TS_ISO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+CP_FILE="$CP_DIR/auto-$TS_FILE-mechanical.md"
+
+# Frontmatter from helper, augmented with checkpoint_kind
+FRONT=$(CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$PROJECT_DIR/.claude/hooks/checkpoint-helper.sh" frontmatter 2>/dev/null)
+# Insert checkpoint_kind: auto-mechanical before closing ---
+FRONT=$(printf '%s' "$FRONT" | awk '
+  /^---$/ { count++ }
+  count == 2 && !done { print "checkpoint_kind: auto-mechanical"; done=1 }
+  { print }
+')
+
+# Activity summary from the log
+ACTIVITY_SUMMARY=$(awk -v cutoff="$LAST_CP" '$1 > cutoff' "$ACTIVITY_LOG" 2>/dev/null | python3 -c '
+import sys, collections, os
+lines = [l.strip() for l in sys.stdin if l.strip()]
+tools = collections.Counter()
+files = collections.Counter()
+for ln in lines:
+    parts = ln.split(" ", 2)
+    if len(parts) < 2: continue
+    tool = parts[1]
+    target = parts[2] if len(parts) > 2 else ""
+    tools[tool] += 1
+    if target and tool in ("Edit", "Write", "Read"):
+        files[target] += 1
+print("### Tool calls")
+for t, n in tools.most_common(8):
+    print(f"- {n}× {t}")
+if files:
+    print("\n### Files touched")
+    for f, n in files.most_common(8):
+        print(f"- {f} ({n})")
+print(f"\n_total tool calls in window: {sum(tools.values())}_")
+' 2>/dev/null)
+
+# Git state (best-effort, may be absent in non-git dirs)
+GIT_BRANCH=$(cd "$PROJECT_DIR" && git branch --show-current 2>/dev/null)
+GIT_STATUS=$(cd "$PROJECT_DIR" && git status --short 2>/dev/null | head -20)
+GIT_LOG=$(cd "$PROJECT_DIR" && git log --oneline -5 2>/dev/null)
+
+{
+  printf '%s\n\n' "$FRONT"
+  printf '# Auto-checkpoint (mechanical): %s\n\n' "$TS_ISO"
+  printf '_window: last %s min, %s tool calls_\n\n' "$INTERVAL_MIN" "$SINCE_LINES"
+  printf '## Activity\n\n%s\n\n' "$ACTIVITY_SUMMARY"
+  if [ -n "$GIT_BRANCH" ]; then
+    printf '## Git\n\n'
+    printf '**Branch:** %s\n\n' "$GIT_BRANCH"
+    if [ -n "$GIT_STATUS" ]; then
+      printf '**Status:**\n```\n%s\n```\n\n' "$GIT_STATUS"
+    else
+      printf '**Status:** clean\n\n'
+    fi
+    if [ -n "$GIT_LOG" ]; then
+      printf '**Recent commits:**\n```\n%s\n```\n' "$GIT_LOG"
+    fi
+  fi
+} > "$CP_FILE"
+
+# Update latest.md so /restore picks it up
+cp "$CP_FILE" "$CP_DIR/latest.md" 2>/dev/null
+echo "$NOW" > "$LAST_CP_FILE"
+
+# Send AutoCheckpoint event to watchtower with inline content
+if [ -x "$PROJECT_DIR/.claude/hooks/watchtower-send.sh" ]; then
+  PREVIEW=$(head -c 2000 "$CP_FILE")
+  PAYLOAD=$(PREVIEW_PATH="$CP_FILE" PREVIEW="$PREVIEW" INTERVAL_MIN="$INTERVAL_MIN" SINCE_LINES="$SINCE_LINES" CWD_VAR="$PROJECT_DIR" python3 -c '
+import json, os
+print(json.dumps({
+    "checkpoint_kind": "auto-mechanical",
+    "checkpoint_path": os.environ["PREVIEW_PATH"],
+    "checkpoint_preview": os.environ["PREVIEW"],
+    "interval_minutes": int(os.environ["INTERVAL_MIN"]),
+    "tool_calls_in_window": int(os.environ["SINCE_LINES"]),
+    "cwd": os.environ["CWD_VAR"],
+}))
+' 2>/dev/null)
+  printf '%s' "$PAYLOAD" | CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$PROJECT_DIR/.claude/hooks/watchtower-send.sh" AutoCheckpoint 2>/dev/null
+fi
+
+exit 0

package/hooks/confirm-helper.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# UV Suite helper: toggle confirm-mode or change the threshold.
+# Used by the /confirm slash command. Extracted into a script so the
+# slash command can avoid inline ${...} expansions, which Claude Code's
+# permission heuristic flags as obfuscation.
+#
+# Usage:
+#   confirm-helper.sh           # show status
+#   confirm-helper.sh status
+#   confirm-helper.sh on
+#   confirm-helper.sh off
+#   confirm-helper.sh <number>  # set threshold
+
+STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.uv-suite-state"
+mkdir -p "$STATE_DIR"
+MODE_FILE="$STATE_DIR/confirm-mode.txt"
+THRESH_FILE="$STATE_DIR/confirm-threshold.txt"
+
+current_mode() { cat "$MODE_FILE" 2>/dev/null || echo "on"; }
+current_thresh() { cat "$THRESH_FILE" 2>/dev/null || echo "50"; }
+
+ARG=$(printf '%s' "$1" | tr -d '[:space:]')
+
+case "$ARG" in
+  on)
+    echo "on" > "$MODE_FILE"
+    echo "Confirm mode: ON (threshold: $(current_thresh) words)"
+    ;;
+  off)
+    echo "off" > "$MODE_FILE"
+    echo "Confirm mode: OFF"
+    ;;
+  ""|status)
+    echo "Confirm mode: $(current_mode) (threshold: $(current_thresh) words)"
+    ;;
+  *)
+    if printf '%s' "$ARG" | grep -qE '^[0-9]+$'; then
+      echo "$ARG" > "$THRESH_FILE"
+      echo "Threshold set to $ARG words (mode: $(current_mode))"
+    else
+      echo "Usage: /confirm [on | off | <number> | status]"
+      exit 1
+    fi
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.26.5",
+  "version": "0.27.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

@@ -37,14 +37,22 @@
       "Bash(wc *)",
       "Bash(head *)",
       "Bash(tail *)",
-      "Bash(curl *)"
+      "Bash(curl *)",
+      "Bash(chmod *)",
+      "Bash(rm /tmp/*)",
+      "Bash(echo *)",
+      "Bash(printf *)",
+      "Bash(node --check *)",
+      "Bash(bash -n *)"
     ],
     "deny": [
       "Bash(rm -rf /)",
       "Bash(rm -rf ~)",
       "Bash(sudo rm -rf *)",
       "Bash(git push --force * main)",
-      "Bash(git push --force * master)"
+      "Bash(git push --force * master)",
+      "Bash(rm -rf .)",
+      "Bash(sudo rm *)"
     ]
   },
   "hooks": {
@@ -155,6 +163,12 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-checkpoint.sh",
+            "timeout": 5,
+            "async": true
           }
         ]
       },

package/personas/professional.json

@@ -33,7 +33,16 @@
       "Bash(npx prettier *)",
       "Bash(pytest *)",
       "Bash(go test *)",
-      "Bash(cargo test *)"
+      "Bash(cargo test *)",
+      "Bash(chmod *)",
+      "Bash(mkdir *)",
+      "Bash(rm /tmp/*)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(echo *)",
+      "Bash(printf *)",
+      "Bash(node --check *)",
+      "Bash(bash -n *)"
     ],
     "deny": [
       "Bash(rm -rf /)",
@@ -42,7 +51,8 @@
       "Bash(sudo rm *)",
       "Bash(git push --force * main)",
       "Bash(git push --force * master)",
-      "Bash(git reset --hard origin/*)"
+      "Bash(git reset --hard origin/*)",
+      "Bash(sudo rm -rf *)"
     ]
   },
   "hooks": {
@@ -164,6 +174,12 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-checkpoint.sh",
+            "timeout": 5,
+            "async": true
           }
         ]
       },

package/personas/spike.json

@@ -22,15 +22,30 @@
       "Bash(find *)",
       "Bash(wc *)",
       "Bash(head *)",
-      "Bash(tail *)"
+      "Bash(tail *)",
+      "Edit(*)",
+      "Bash(git *)",
+      "Bash(npx prettier *)",
+      "Bash(npx markdown-* *)",
+      "Bash(curl *)",
+      "Bash(chmod *)",
+      "Bash(mkdir *)",
+      "Bash(rm /tmp/*)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(echo *)",
+      "Bash(printf *)",
+      "Bash(node --check *)",
+      "Bash(bash -n *)"
     ],
     "deny": [
-      "Edit(*)",
-      "Bash(git commit *)",
-      "Bash(git push *)",
-      "Bash(rm *)",
-      "Bash(npm run *)",
-      "Bash(npx *)"
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf .)",
+      "Bash(sudo rm *)",
+      "Bash(sudo rm -rf *)",
+      "Bash(git push --force * main)",
+      "Bash(git push --force * master)"
     ]
   },
   "hooks": {
@@ -123,6 +138,12 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-checkpoint.sh",
+            "timeout": 5,
+            "async": true
           }
         ]
       },

package/personas/sport.json

@@ -16,7 +16,25 @@
       "Bash(npm *)",
       "Bash(npx *)",
       "Bash(node *)",
-      "Bash(git *)"
+      "Bash(git *)",
+      "Bash(chmod *)",
+      "Bash(mkdir *)",
+      "Bash(rm /tmp/*)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(echo *)",
+      "Bash(printf *)",
+      "Bash(node --check *)",
+      "Bash(bash -n *)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf .)",
+      "Bash(sudo rm *)",
+      "Bash(sudo rm -rf *)",
+      "Bash(git push --force * main)",
+      "Bash(git push --force * master)"
     ]
   },
   "hooks": {
@@ -109,6 +127,12 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-checkpoint.sh",
+            "timeout": 5,
+            "async": true
           }
         ]
       },

package/skills/auto-checkpoint/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: auto-checkpoint
+description: >
+  Toggle automatic checkpoints, or change how often they fire. When on,
+  UV Suite writes a checkpoint every N minutes (default 10): a mechanical
+  state snapshot from the PostToolUse hook, plus a semantic summary written
+  by Claude (via `claude -p --bare --model haiku`) from the Watchtower's
+  timer. Sessions with no activity in the window are skipped.
+argument-hint: "[on|off|<minutes>|status]"
+user-invocable: true
+allowed-tools:
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/auto-checkpoint-helper.sh *)
+---
+
+## Apply /auto-checkpoint $ARGUMENTS
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/auto-checkpoint-helper.sh $ARGUMENTS`
+
+## Instructions
+
+Show the user the line of output above as the response — it confirms what
+changed. Do not add commentary. The change applies to the very next interval;
+no restart needed.
+
+## What this controls
+
+- `on` / `off` — enable or disable both tiers (mechanical + semantic).
+- `<minutes>` — set the checkpoint interval (1-1440). Default 10.
+- `status` (or no argument) — print the current mode and interval.
+
+## How it works
+
+- **Tier A (mechanical):** the `auto-checkpoint.sh` hook runs after each tool
+  call. When the interval has passed and there's been activity since the last
+  checkpoint, it writes a deterministic snapshot — git state, recent tool calls,
+  files touched — to `uv-out/checkpoints/<sid>/auto-<ts>-mechanical.md`.
+- **Tier B (semantic):** the Watchtower process (`uvs watch`) keeps a timer.
+  Every N minutes, for each active session, it shells out to `claude -p --bare
+  --model haiku` with a prompt assembled from the recent dashboard events and
+  git state. Output is saved next to the mechanical checkpoint as
+  `auto-<ts>-semantic.md`. Cap: `--max-budget-usd 0.05` per call.
+- Both tiers fire `AutoCheckpoint` events to the Watchtower so they show up as
+  distinct rows on the dashboard.
+- Sessions with zero activity in the interval are skipped — no empty checkpoints.
+
+State lives in `.uv-suite-state/auto-checkpoint.json` (mode + interval) and
+`.uv-suite-state/sessions/<sid>.last-{mechanical,semantic}-checkpoint.txt`.

package/skills/confirm/SKILL.md

@@ -7,15 +7,12 @@ description: >
 argument-hint: "[on|off|<number>|status]"
 user-invocable: true
 allowed-tools:
-  - Bash(mkdir *)
-  - Bash(echo *)
-  - Bash(cat *)
-  - Bash(printf *)
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/confirm-helper.sh *)
 ---
 
 ## Apply /confirm $ARGUMENTS
 
-!`STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.uv-suite-state"; mkdir -p "$STATE_DIR"; MODE_FILE="$STATE_DIR/confirm-mode.txt"; THRESH_FILE="$STATE_DIR/confirm-threshold.txt"; ARG=$(printf '%s' "$ARGUMENTS" | tr -d '[:space:]'); current_mode() { cat "$MODE_FILE" 2>/dev/null || echo "on"; }; current_thresh() { cat "$THRESH_FILE" 2>/dev/null || echo "50"; }; case "$ARG" in on) echo "on" > "$MODE_FILE"; echo "Confirm mode: ON (threshold: $(current_thresh) words)";; off) echo "off" > "$MODE_FILE"; echo "Confirm mode: OFF";; ''|status) echo "Confirm mode: $(current_mode) (threshold: $(current_thresh) words)";; *) if printf '%s' "$ARG" | grep -qE '^[0-9]+$'; then echo "$ARG" > "$THRESH_FILE"; echo "Threshold set to $ARG words (mode: $(current_mode))"; else echo "Usage: /confirm [on | off | <number> | status]"; fi;; esac`
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/confirm-helper.sh $ARGUMENTS`
 
 ## Instructions
 
@@ -31,5 +28,5 @@ next user prompt; no restart needed.
   step. Slash commands (`/foo ...`) are always exempt.
 - `status` (or no argument) — print the current mode and threshold.
 
-State lives in `${CLAUDE_PROJECT_DIR}/.uv-suite-state/confirm-mode.txt` and
-`confirm-threshold.txt`. Defaults if missing: mode `on`, threshold `50`.
+State lives in `.uv-suite-state/confirm-mode.txt` and `.uv-suite-state/confirm-threshold.txt`
+under `$CLAUDE_PROJECT_DIR`. Defaults if missing: mode `on`, threshold `50`.

package/watchtower/auto-checkpoint-prompt.md

@@ -0,0 +1,51 @@
+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.
+
+## Session
+
+- name: {{name}}
+- kind: {{kind}}
+- priority: {{priority}}
+- persona: {{persona}}
+- purpose: {{purpose}}
+- elapsed since last semantic checkpoint: {{elapsed_min}} min
+
+## Activity (last {{interval_min}} min, from the dashboard)
+
+{{event_list}}
+
+## Git
+
+```
+{{git_branch}}
+{{git_status}}
+{{git_log}}
+```
+
+## Write the checkpoint
+
+Output **only** the markdown body below — no preamble, no closing remarks.
+Use this exact shape, max 30 lines total:
+
+```markdown
+# Auto-checkpoint: {{timestamp}}
+
+## 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.
+
+## Files touched
+- list (omit section if empty)
+
+## In progress
+- 1-2 bullets — what the session appears to be working on right now, based
+  on the latest events.
+
+## 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.
+```
+
+If the activity log is sparse or ambiguous, say so plainly in "In progress"
+rather than inventing details.

package/watchtower/auto-checkpoint-runner.js

@@ -0,0 +1,285 @@
+// 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.
+
+const fs = require("fs");
+const path = require("path");
+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 MAX_BUDGET_USD = "0.05";
+const MODEL = "haiku";
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function readStringSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+
+// Returns { mode, interval_minutes } — defaults if state file missing.
+function readAutoCheckpointState(projectDir) {
+  const f = path.join(projectDir, ".uv-suite-state", "auto-checkpoint.json");
+  const d = readJsonSafe(f);
+  return {
+    mode: d?.mode ?? "on",
+    interval_minutes: d?.interval_minutes ?? DEFAULT_INTERVAL_MIN,
+  };
+}
+
+// Group events by session, keep the most recent set per session.
+function groupActiveSessions(events, windowMs) {
+  const cutoff = Date.now() - windowMs;
+  const bySession = new Map();
+  for (const ev of events) {
+    const sid = ev.uvs_session_id || ev.session_id;
+    if (!sid) continue;
+    if ((ev._ts || 0) < cutoff) continue;
+    if (!bySession.has(sid)) {
+      bySession.set(sid, {
+        sid,
+        cwd: ev.cwd,
+        session_name: ev.session_name || "",
+        session_kind: ev.session_kind || "",
+        session_priority: ev.session_priority || "",
+        session_purpose: ev.session_purpose || "",
+        persona: ev.persona || "",
+        events: [],
+      });
+    }
+    bySession.get(sid).events.push(ev);
+  }
+  return [...bySession.values()];
+}
+
+function eventToCompactLine(ev) {
+  const t = ev.event_type || ev.hook_event_name || "?";
+  const tool = ev.tool_name || "";
+  const input = ev.tool_input || {};
+  const target =
+    input.file_path ||
+    input.command ||
+    input.pattern ||
+    input.url ||
+    input.description ||
+    "";
+  const ts = new Date(ev._ts || Date.now()).toISOString().slice(11, 19);
+  let label = t;
+  if (tool) label += ` ${tool}`;
+  if (target) label += ` ${String(target).slice(0, 80)}`;
+  return `  ${ts}  ${label}`;
+}
+
+function gitState(cwd) {
+  return new Promise((resolve) => {
+    const out = { branch: "", status: "", log: "" };
+    let pending = 3;
+    const done = () => {
+      if (--pending === 0) resolve(out);
+    };
+    const run = (args, key) => {
+      const child = spawn("git", args, { cwd });
+      let buf = "";
+      child.stdout.on("data", (d) => (buf += d));
+      child.on("close", () => {
+        out[key] = buf.trim();
+        done();
+      });
+      child.on("error", () => done());
+    };
+    run(["branch", "--show-current"], "branch");
+    run(["status", "--short"], "status");
+    run(["log", "--oneline", "-5"], "log");
+  });
+}
+
+function buildPrompt(template, ctx) {
+  let out = template;
+  for (const [k, v] of Object.entries(ctx)) {
+    out = out.split(`{{${k}}}`).join(v ?? "");
+  }
+  return out;
+}
+
+function runClaudeP(prompt) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      "claude",
+      ["-p", "--bare", "--model", MODEL, "--max-budget-usd", MAX_BUDGET_USD],
+      { stdio: ["pipe", "pipe", "pipe"] },
+    );
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (err) =>
+      resolve({ ok: false, stdout, stderr, error: err.message }),
+    );
+    child.on("close", (code) =>
+      resolve({ ok: code === 0, stdout, stderr, code }),
+    );
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
+let promptTemplate = null;
+function loadPromptTemplate() {
+  if (promptTemplate) return promptTemplate;
+  try {
+    promptTemplate = fs.readFileSync(PROMPT_TEMPLATE_PATH, "utf-8");
+  } catch {
+    promptTemplate = null;
+  }
+  return promptTemplate;
+}
+
+async function processSession(session, broadcast) {
+  const { sid, cwd, events } = session;
+  if (!cwd || !sid) return;
+
+  const state = readAutoCheckpointState(cwd);
+  if (state.mode !== "on") return;
+  const intervalMs = state.interval_minutes * 60 * 1000;
+
+  const lastFile = path.join(
+    cwd,
+    ".uv-suite-state",
+    "sessions",
+    `${sid}.last-semantic-checkpoint.txt`,
+  );
+  const lastTs = parseInt(readStringSafe(lastFile) || "0", 10);
+  const now = Date.now();
+  if (now - lastTs * 1000 < intervalMs) return;
+
+  // Activity since last checkpoint
+  const recent = events
+    .filter((e) => (e._ts || 0) > lastTs * 1000)
+    .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;
+  }
+
+  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 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;
+  }
+
+  // Write the checkpoint file
+  const cpDir = path.join(cwd, "uv-out", "checkpoints", sid);
+  fs.mkdirSync(cpDir, { recursive: true });
+  const tsFile = new Date(now)
+    .toISOString()
+    .slice(0, 16)
+    .replace(/[T:]/g, "-")
+    .replace(/-(\d\d)$/, "$1");
+  const cpFile = path.join(cpDir, `auto-${tsFile}-semantic.md`);
+
+  const frontmatter = [
+    "---",
+    `uvs_session_id: ${sid}`,
+    `session_name: ${session.session_name || ""}`,
+    `session_kind: ${session.session_kind || ""}`,
+    `session_purpose: ${session.session_purpose || ""}`,
+    `session_priority: ${session.session_priority || ""}`,
+    `persona: ${session.persona || ""}`,
+    `checkpoint_at: ${new Date(now).toISOString()}`,
+    `checkpoint_kind: auto-semantic`,
+    "---",
+    "",
+  ].join("\n");
+
+  fs.writeFileSync(cpFile, frontmatter + result.stdout.trim() + "\n");
+  fs.writeFileSync(lastFile, String(Math.floor(now / 1000)));
+
+  // Broadcast as AutoCheckpoint event
+  const preview = (frontmatter + result.stdout).slice(0, 2000);
+  const event = {
+    event_type: "AutoCheckpoint",
+    source_app: path.basename(cwd),
+    cwd,
+    uvs_session_id: sid,
+    session_id: sid,
+    session_name: session.session_name,
+    session_kind: session.session_kind,
+    session_priority: session.session_priority,
+    persona: session.persona,
+    checkpoint_kind: "auto-semantic",
+    checkpoint_path: cpFile,
+    checkpoint_preview: preview,
+    interval_minutes: state.interval_minutes,
+    tool_calls_in_window: recent.length,
+    _ts: now,
+  };
+  broadcast(event);
+}
+
+// One pass over all sessions with recent activity. Exposed so tests (and
+// any future "force a checkpoint now" command) can drive a single tick.
+async function tick({ getEvents, broadcast }) {
+  try {
+    const events = getEvents();
+    const window = 60 * 60 * 1000; // 1h lookback for active sessions
+    const sessions = groupActiveSessions(events, window);
+    for (const s of sessions) {
+      await processSession(s, broadcast);
+    }
+  } catch (err) {
+    console.warn("[auto-checkpoint] tick error:", err.message);
+  }
+}
+
+// Public API: start the runner. `getEvents` returns the watchtower's event
+// store; `broadcast` injects an AutoCheckpoint event into the SSE stream.
+// First tick after POLL_INTERVAL_MS; subsequent ticks every POLL_INTERVAL_MS.
+function start({ getEvents, broadcast }) {
+  const handle = setInterval(
+    () => tick({ getEvents, broadcast }),
+    POLL_INTERVAL_MS,
+  );
+  return () => clearInterval(handle);
+}
+
+module.exports = { start, tick };

package/watchtower/dashboard.html

@@ -357,6 +357,53 @@
   .type-Notification { color: var(--warning); }
   .type-PermissionRequest { color: var(--danger-soft); }
   .type-PreCompact { color: var(--text-muted); }
+  .type-AutoCheckpoint { color: var(--success); font-weight: 700; }
+
+  /* Auto-checkpoint rows are full-width and expandable */
+  .event.checkpoint {
+    background: rgba(48, 209, 88, 0.06);
+    border-left: 3px solid var(--success);
+    padding-left: 25px;
+    opacity: 1;
+  }
+  .event.checkpoint .detail { cursor: pointer; }
+  .event.checkpoint .checkpoint-summary {
+    color: var(--text);
+    font-weight: 500;
+  }
+  .event.checkpoint .checkpoint-kind {
+    display: inline-block;
+    margin-left: 8px;
+    padding: 1px 6px;
+    font-size: 10.5px;
+    font-weight: 600;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    border-radius: 4px;
+    background: var(--success-soft);
+    color: var(--success);
+    vertical-align: 1px;
+  }
+  .event.checkpoint .checkpoint-body {
+    display: none;
+    margin-top: 10px;
+    padding: 12px 14px;
+    background: var(--surface);
+    border-radius: 6px;
+    color: var(--text-muted);
+    font-family: var(--font-mono);
+    font-size: 12.5px;
+    white-space: pre-wrap;
+    line-height: 1.55;
+    max-height: 360px;
+    overflow-y: auto;
+  }
+  .event.checkpoint.expanded .checkpoint-body { display: block; }
+  .event.checkpoint .checkpoint-toggle {
+    color: var(--text-dim);
+    font-size: 12px;
+    margin-left: 8px;
+  }
 </style>
 </head>
 <body>
@@ -603,11 +650,13 @@ function renderEvent(ev) {
   const fail = isFailure(ev);
   const boundary = isSessionBoundary(ev);
   const prompt = isUserPrompt(ev);
+  const checkpoint = type === 'AutoCheckpoint';
   const priority = sessions[sid]?.priority || '';
 
   const div = document.createElement('div');
   let cls = 'event';
-  if (human) cls += ' needs-human';
+  if (checkpoint) cls += ' checkpoint';
+  else if (human) cls += ' needs-human';
   else if (fail) cls += ' failure';
   else if (prompt) cls += ' user-prompt';
   else if (boundary) cls += ' session-boundary';
@@ -617,13 +666,32 @@ function renderEvent(ev) {
 
   const humanBadge = human ? '<span class="human-badge">NEEDS HUMAN</span>' : '';
 
-  div.innerHTML = `
-    <span class="time">${formatTime(ev._ts)}</span>
-    <span class="type type-${type}">${type}${humanBadge}</span>
-    <span class="session" style="background:${color}22;color:${color}" title="${sessionDisplayName(sid)}">${shortSession(sid)}</span>
-    <span class="tool">${tool}</span>
-    <span class="detail">${eventDetail(ev)}</span>
-  `;
+  if (checkpoint) {
+    const kind = ev.checkpoint_kind || 'auto';
+    const kindLabel = kind === 'auto-mechanical' ? 'mechanical' : kind === 'auto-semantic' ? 'semantic' : kind;
+    const calls = ev.tool_calls_in_window || 0;
+    const interval = ev.interval_minutes || '';
+    const summary = `<span class="checkpoint-summary">${escapeHtml(ev.checkpoint_path?.split('/').slice(-1)[0] || 'checkpoint')}</span>` +
+                    `<span class="checkpoint-kind">${kindLabel}</span>` +
+                    `<span class="checkpoint-toggle">${calls} tool calls in last ${interval}m · click to expand</span>`;
+    const body = ev.checkpoint_preview ? `<div class="checkpoint-body">${escapeHtml(ev.checkpoint_preview)}</div>` : '';
+    div.innerHTML = `
+      <span class="time">${formatTime(ev._ts)}</span>
+      <span class="type type-${type}">${type}</span>
+      <span class="session" style="background:${color}22;color:${color}" title="${sessionDisplayName(sid)}">${shortSession(sid)}</span>
+      <span class="tool"></span>
+      <span class="detail">${summary}${body}</span>
+    `;
+    div.querySelector('.detail').addEventListener('click', () => div.classList.toggle('expanded'));
+  } else {
+    div.innerHTML = `
+      <span class="time">${formatTime(ev._ts)}</span>
+      <span class="type type-${type}">${type}${humanBadge}</span>
+      <span class="session" style="background:${color}22;color:${color}" title="${sessionDisplayName(sid)}">${shortSession(sid)}</span>
+      <span class="tool">${tool}</span>
+      <span class="detail">${eventDetail(ev)}</span>
+    `;
+  }
 
   div._ev = ev;
 

package/watchtower/server.js

@@ -8,6 +8,7 @@ const http = require("http");
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
+const autoCheckpointRunner = require("./auto-checkpoint-runner");
 
 const PORT = process.env.UVS_WATCHTOWER_PORT || 4200;
 const DATA_FILE = path.join(__dirname, "events.json");
@@ -176,4 +177,24 @@ server.listen(PORT, () => {
   console.log(
     `Waiting for hook events on POST http://localhost:${PORT}/events`,
   );
+
+  // Tier B auto-checkpoint runner. Polls every minute, calls
+  // `claude -p --bare --model haiku` for each active session whose
+  // configured interval has elapsed. Disable with `/auto-checkpoint off`
+  // per project, or set UVS_AUTO_CHECKPOINT_DISABLED=1 to disable globally.
+  if (!process.env.UVS_AUTO_CHECKPOINT_DISABLED) {
+    autoCheckpointRunner.start({
+      getEvents: () => events,
+      broadcast: (ev) => {
+        ev._ts = ev._ts || Date.now();
+        ev._id = crypto.randomUUID();
+        events.push(ev);
+        broadcast(ev);
+        saveEvents();
+      },
+    });
+    console.log(
+      "Auto-checkpoint runner started (Tier B, polls every 60s, uses claude -p)",
+    );
+  }
 });