uv-suite 0.28.0 → 0.30.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 /session 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 \`/session restore $UVS_RESTORE_FROM\` to load the prior session's latest checkpoint. After /session 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/checkpoint-helper.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # UV Suite helper: locate per-session checkpoint paths and print metadata.
-# Used by the /checkpoint and /restore slash commands.
+# Used by the /session checkpoint and /session restore slash commands.
 #
 # Usage:
 #   checkpoint-helper.sh dir       # ensure + print the dir for current session
@@ -16,11 +16,14 @@ resolve_paths() {
   if [ -z "$SID" ] && [ -f "$STATE_DIR/current-session.txt" ]; then
     SID=$(cat "$STATE_DIR/current-session.txt" 2>/dev/null)
   fi
-  CHECKPOINTS_ROOT="$PROJECT_DIR/uv-out/checkpoints"
-  SESSION_CP_DIR=""
-  [ -n "$SID" ] && SESSION_CP_DIR="$CHECKPOINTS_ROOT/$SID"
-  META_FILE=""
-  [ -n "$SID" ] && META_FILE="$STATE_DIR/sessions/$SID.json"
+  [ -z "$SID" ] && SID="no-session"
+  # Unified layout: everything a session produces lives under uv-out/sessions/<sid>/.
+  SESSIONS_ROOT="$PROJECT_DIR/uv-out/sessions"
+  SESSION_CP_DIR="$SESSIONS_ROOT/$SID/checkpoints"
+  # Legacy locations, read for backward compatibility (pre-unify checkpoints):
+  LEGACY_CP_ROOT="$PROJECT_DIR/uv-out/checkpoints"
+  LEGACY_SESSION_CP_DIR="$LEGACY_CP_ROOT/$SID"
+  META_FILE="$STATE_DIR/sessions/$SID.json"
 }
 
 print_meta_field() {
@@ -37,13 +40,8 @@ resolve_paths
 
 case "$1" in
   dir)
-    if [ -n "$SESSION_CP_DIR" ]; then
-      mkdir -p "$SESSION_CP_DIR"
-      echo "$SESSION_CP_DIR"
-    else
-      mkdir -p "$CHECKPOINTS_ROOT"
-      echo "$CHECKPOINTS_ROOT"
-    fi
+    mkdir -p "$SESSION_CP_DIR"
+    echo "$SESSION_CP_DIR"
     ;;
   meta)
     echo "uvs_session_id=${SID:-}"
@@ -73,25 +71,32 @@ checkpoint_at: ${NOW}
 EOF
     ;;
   latest)
-    if [ -n "$SESSION_CP_DIR" ] && [ -f "$SESSION_CP_DIR/latest.md" ]; then
+    if [ -f "$SESSION_CP_DIR/latest.md" ]; then
       cat "$SESSION_CP_DIR/latest.md"
-    elif [ -f "$CHECKPOINTS_ROOT/latest.md" ]; then
-      echo "(no per-session checkpoint for ${SID:-this session}; showing legacy global latest.md)"
+    elif [ -f "$LEGACY_SESSION_CP_DIR/latest.md" ]; then
+      echo "(no checkpoint at new path; showing legacy uv-out/checkpoints/${SID}/latest.md)"
+      echo
+      cat "$LEGACY_SESSION_CP_DIR/latest.md"
+    elif [ -f "$LEGACY_CP_ROOT/latest.md" ]; then
+      echo "(no per-session checkpoint for ${SID}; showing legacy global latest.md)"
       echo
-      cat "$CHECKPOINTS_ROOT/latest.md"
+      cat "$LEGACY_CP_ROOT/latest.md"
     else
-      echo "No checkpoint found at $CHECKPOINTS_ROOT. Run /checkpoint to create one."
+      echo "No checkpoint found for session ${SID}. Run /session checkpoint to create one."
     fi
     ;;
   list)
-    [ ! -d "$CHECKPOINTS_ROOT" ] && { echo "No checkpoints directory at $CHECKPOINTS_ROOT"; exit 0; }
     found=0
-    for d in "$CHECKPOINTS_ROOT"/*/; do
-      [ -d "$d" ] || continue
-      cp_sid=$(basename "$d")
-      cp_meta="$STATE_DIR/sessions/$cp_sid.json"
-      cp_name=""
-      cp_priority=""
+    seen=" "
+    emit_cp_entry() { # $1 = cp_sid  $2 = checkpoint dir  $3 = origin tag
+      local cp_sid="$1" d="$2" origin="$3"
+      [ -d "$d" ] || return 0
+      case "$seen" in *" $cp_sid "*) return 0 ;; esac   # dedupe sid across new+legacy
+      local latest
+      latest=$(ls -t "$d"/*.md 2>/dev/null | head -1)
+      [ -z "$latest" ] && return 0
+      seen="$seen$cp_sid "
+      local cp_meta="$STATE_DIR/sessions/$cp_sid.json" cp_name="" cp_priority=""
       if [ -f "$cp_meta" ]; then
         if command -v jq >/dev/null 2>&1; then
           cp_name=$(jq -r '.name // ""' "$cp_meta" 2>/dev/null)
@@ -100,20 +105,20 @@ EOF
           cp_name=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "$cp_meta" | head -1 | sed 's/.*"name"[[:space:]]*:[[:space:]]*"\(.*\)"/\1/')
         fi
       fi
-      latest=$(ls -t "$d"*.md 2>/dev/null | head -1)
-      [ -z "$latest" ] && continue
+      local ts label mark
       ts=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$latest" 2>/dev/null || stat -c '%y' "$latest" 2>/dev/null | cut -c1-16)
       label="${cp_name:-(unlabeled)}"
       [ -n "$cp_priority" ] && label="$label [p:$cp_priority]"
-      mark=" "
-      [ "$cp_sid" = "$SID" ] && mark="*"
-      echo "$mark ${cp_sid:0:8}  $ts  $label"
+      mark=" "; [ "$cp_sid" = "$SID" ] && mark="*"
+      echo "$mark ${cp_sid:0:8}  $ts  $label${origin}"
       found=1
-    done
-    [ "$found" -eq 0 ] && echo "No per-session checkpoints yet (current session: ${SID:-none})"
-    # Note legacy global checkpoint if present
-    if [ -f "$CHECKPOINTS_ROOT/latest.md" ]; then
-      ts=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$CHECKPOINTS_ROOT/latest.md" 2>/dev/null || stat -c '%y' "$CHECKPOINTS_ROOT/latest.md" 2>/dev/null | cut -c1-16)
+    }
+    # New unified layout first, then legacy, deduped by sid.
+    for d in "$SESSIONS_ROOT"/*/checkpoints/; do emit_cp_entry "$(basename "$(dirname "$d")")" "$d" ""; done
+    for d in "$LEGACY_CP_ROOT"/*/; do emit_cp_entry "$(basename "$d")" "$d" "  (legacy path)"; done
+    [ "$found" -eq 0 ] && echo "No per-session checkpoints yet (current session: ${SID})"
+    if [ -f "$LEGACY_CP_ROOT/latest.md" ]; then
+      ts=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$LEGACY_CP_ROOT/latest.md" 2>/dev/null || stat -c '%y' "$LEGACY_CP_ROOT/latest.md" 2>/dev/null | cut -c1-16)
       echo "  legacy   $ts  (pre-metadata global latest.md)"
     fi
     ;;

package/hooks/git-context.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# UV Suite helper: resolve git worktree context for a directory, as a JSON object.
+# Used to stamp session metadata so the Watchtower can tell apart sessions running
+# in different worktrees of the same repo (e.g. a feature worktree vs the main checkout).
+#
+# Usage: git-context.sh [dir]   (defaults to current directory)
+# Prints: {} if not a git repo, else:
+#   {
+#     "git_worktree":          "/abs/path/to/worktree-root",
+#     "git_branch":            "feature-x",
+#     "git_main_repo":         "/abs/path/to/main/checkout",
+#     "git_is_linked_worktree": true|false
+#   }
+
+DIR="${1:-.}"
+cd "$DIR" 2>/dev/null || { echo '{}'; exit 0; }
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo '{}'; exit 0; }
+
+WT=$(git rev-parse --show-toplevel 2>/dev/null)
+BR=$(git branch --show-current 2>/dev/null)
+GITDIR=$(git rev-parse --absolute-git-dir 2>/dev/null)
+
+# A linked worktree's git dir lives under <main>/.git/worktrees/<name>.
+case "$GITDIR" in
+  */worktrees/*) LINKED=true ;;
+  *)             LINKED=false ;;
+esac
+
+# Common dir points at the shared .git; its parent is the main checkout.
+COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
+case "$COMMON" in /*) ;; *) COMMON="$WT/$COMMON" ;; esac
+MAIN_REPO=$(cd "$(dirname "$COMMON")" 2>/dev/null && pwd)
+[ -z "$MAIN_REPO" ] && MAIN_REPO="$WT"
+
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg wt "$WT" --arg br "$BR" --arg main "$MAIN_REPO" --argjson linked "$LINKED" \
+    '{git_worktree: $wt, git_branch: $br, git_main_repo: $main, git_is_linked_worktree: $linked}'
+else
+  printf '{"git_worktree":"%s","git_branch":"%s","git_main_repo":"%s","git_is_linked_worktree":%s}\n' \
+    "$WT" "$BR" "$MAIN_REPO" "$LINKED"
+fi

package/hooks/lite-mode-inject.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# UV Suite Hook: Lite mode — inject terseness instructions
+# Event: UserPromptSubmit
+# Activates when UVS_LITE=1 OR .uv-suite-state/lite-mode.txt contains "on".
+# Reduces output verbosity to save tokens.
+
+STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.uv-suite-state"
+STATE_FILE="$STATE_DIR/lite-mode.txt"
+
+is_lite="false"
+[ "$UVS_LITE" = "1" ] && is_lite="true"
+[ -f "$STATE_FILE" ] && [ "$(cat "$STATE_FILE" 2>/dev/null | tr -d '[:space:]')" = "on" ] && is_lite="true"
+
+if [ "$is_lite" != "true" ]; then
+  exit 0
+fi
+
+cat <<'EOF'
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "UV Suite lite mode is ACTIVE. Follow these rules for this turn:\n- No preamble. No \"I'll do X\" before doing it. Start with the action.\n- No end-of-turn summaries longer than one sentence.\n- No bullet lists unless the user explicitly asks for one.\n- No code comments unless the user asks.\n- No markdown headers (##, ###) in responses unless the user asks.\n- Inline single-sentence updates between tool calls; never multi-paragraph narration.\n- Cite file paths inline (file.ts:42), not as section headers.\n- Skip pleasantries, acknowledgments, and reassurances.\nThe user is token-constrained. Be useful, not thorough."
+  }
+}
+EOF

package/hooks/session-end-helper.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # UV Suite helper: explicit session termination.
-# Used by the /session-end slash command.
+# 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
@@ -53,4 +53,4 @@ print(json.dumps({
 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."
+echo "Run /session checkpoint first if you want a final state snapshot, then exit the terminal."

package/hooks/session-end.sh

@@ -33,11 +33,11 @@ UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null | head -5)
 
 REVIEW_MSG=""
 if [ -n "$STAGED" ] || [ -n "$UNSTAGED" ] || [ -n "$UNTRACKED" ]; then
-  REVIEW_MSG="Uncommitted changes — consider /review and /slop-check before committing. "
+  REVIEW_MSG="Uncommitted changes — consider /review and /review --slop before committing. "
 fi
 
 # Checkpoint prompt
-CHECKPOINT_MSG="Run /checkpoint to save session state for next time. Run /restore at the start of your next session."
+CHECKPOINT_MSG="Run /session checkpoint to save session state for next time. Run /session restore at the start of your next session."
 
 FULL_MSG="${DURATION_MSG}${REVIEW_MSG}${CHECKPOINT_MSG}"
 

package/hooks/session-label-nag.sh

@@ -4,7 +4,7 @@
 #
 # Reads the metadata file at .uv-suite-state/sessions/$UVS_SESSION_ID.json.
 # If the session has no name, injects an additionalContext nudge once every
-# Nth user prompt (default 3) so Claude reminds the user to run /session-init.
+# Nth user prompt (default 3) so Claude reminds the user to run /session init.
 # Skips when the prompt is itself a slash command.
 
 INPUT=$(cat)
@@ -53,7 +53,7 @@ if [ "$COUNT" -ne 1 ] && [ "$REMAINDER" -ne 1 ]; then
   exit 0
 fi
 
-MSG="[uv-suite] This session has no name yet. Briefly remind the user to run /session-init to set name, kind (long-running/outcome), purpose, and priority — these label the session in the watchtower dashboard. One sentence is enough; then proceed with the user's request."
+MSG="[uv-suite] This session has no name yet. Briefly remind the user to run /session init to set name, kind (long-running/outcome), purpose, and priority — these label the session in the watchtower dashboard. One sentence is enough; then proceed with the user's request."
 
 if command -v jq >/dev/null 2>&1; then
   jq -nc --arg ctx "$MSG" '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:$ctx}}'

package/hooks/session-meta.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # UV Suite helper: read or write session metadata.
-# Used by the /session-init slash command.
+# Used by the /session init slash command.
 #
 # Usage:
 #   session-meta.sh show
@@ -40,6 +40,18 @@ print(json.dumps({
 ' > "$META"
 fi
 
+# Refresh git worktree context (worktree path, branch, main repo) so the Watchtower
+# can distinguish sessions running in different worktrees of the same repo.
+GIT_JSON=$("$(dirname "$0")/git-context.sh" "${CLAUDE_PROJECT_DIR:-$(pwd)}" 2>/dev/null)
+if [ -n "$GIT_JSON" ] && [ "$GIT_JSON" != "{}" ] && command -v jq >/dev/null 2>&1; then
+  TMP=$(mktemp)
+  if jq -s '.[0] * .[1]' "$META" <(printf '%s' "$GIT_JSON") > "$TMP" 2>/dev/null; then
+    mv "$TMP" "$META"
+  else
+    rm -f "$TMP"
+  fi
+fi
+
 ACTION="$1"
 shift || true
 
@@ -53,12 +65,17 @@ kind     = d.get("kind", "") or "(unset)"
 purpose  = d.get("purpose", "") or "(unset)"
 priority = d.get("priority", "") or "(unset)"
 persona  = d.get("persona", "") or "(unset)"
+branch   = d.get("git_branch", "") or "(unset)"
+worktree = d.get("git_worktree", "") or "(unset)"
+linked   = d.get("git_is_linked_worktree", False)
 print(f"session: {sid}")
 print(f"  name:     {name}")
 print(f"  kind:     {kind}")
 print(f"  purpose:  {purpose}")
 print(f"  priority: {priority}")
 print(f"  persona:  {persona}")
+print(f"  branch:   {branch}")
+print(f"  worktree: {worktree}" + ("  (linked)" if linked else ""))
 PY
 }
 

package/hooks/session-review-reminder.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # UV Suite Hook: Remind to review before ending session
 # Event: Stop
-# If there are uncommitted changes, reminds the user to run /review and /slop-check.
+# If there are uncommitted changes, reminds the user to run /review and /review --slop.
 
 # Check for uncommitted changes
 STAGED=$(git diff --cached --stat 2>/dev/null)
@@ -28,7 +28,7 @@ fi
 cat <<EOF
 {
   "continue": true,
-  "systemMessage": "SESSION END REMINDER: There are uncommitted changes in the working tree.\n\n${SUMMARY}\nConsider running /review and /slop-check before committing."
+  "systemMessage": "SESSION END REMINDER: There are uncommitted changes in the working tree.\n\n${SUMMARY}\nConsider running /review and /review --slop before committing."
 }
 EOF
 

package/hooks/session-start.sh

@@ -28,6 +28,18 @@ PAYLOAD=""
 META_FILE=""
 [ -n "$SID" ] && META_FILE="$SESSIONS_DIR/$SID.json"
 
+# Refresh git worktree context into the session metadata at each launch (branch can
+# change between sessions), so the Watchtower sees which worktree this session runs in.
+GIT_JSON=$("${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/git-context.sh" "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null)
+if [ -n "$META_FILE" ] && [ -f "$META_FILE" ] && [ -n "$GIT_JSON" ] && [ "$GIT_JSON" != "{}" ] && command -v jq >/dev/null 2>&1; then
+  TMP=$(mktemp)
+  if jq -s '.[0] * .[1]' "$META_FILE" <(printf '%s' "$GIT_JSON") > "$TMP" 2>/dev/null; then
+    mv "$TMP" "$META_FILE"
+  else
+    rm -f "$TMP"
+  fi
+fi
+
 if [ -n "$META_FILE" ] && [ -f "$META_FILE" ] && command -v jq >/dev/null 2>&1; then
   PAYLOAD=$(echo "$INPUT" | jq -c --slurpfile m "$META_FILE" '
     . + {
@@ -37,6 +49,10 @@ if [ -n "$META_FILE" ] && [ -f "$META_FILE" ] && command -v jq >/dev/null 2>&1;
       session_purpose:  ($m[0].purpose // ""),
       session_priority: ($m[0].priority // ""),
       persona:          ($m[0].persona // ""),
+      git_worktree:           ($m[0].git_worktree // ""),
+      git_branch:             ($m[0].git_branch // ""),
+      git_main_repo:          ($m[0].git_main_repo // ""),
+      git_is_linked_worktree: ($m[0].git_is_linked_worktree // false),
       cwd:              (.cwd // $m[0].cwd // "")
     }' 2>/dev/null)
 fi

package/hooks/slop-grep.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # UV Suite Hook: Fast deterministic slop check
 # Event: PostToolUse (Edit|Write)
-# Greps for mechanical, unambiguous slop patterns. No LLM, no false positives.
+# Catches one mechanical pattern: .toBeTruthy() / .toBeDefined() in JS/TS
+# test files. No LLM. Conservative on purpose — false positives erode trust.
 
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
@@ -10,40 +11,20 @@ if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
   exit 0
 fi
 
-EXT="${FILE_PATH##*.}"
-FINDINGS=""
+# Only check JS/TS test files
+if ! echo "$FILE_PATH" | grep -qE "\.(test|spec)\.(ts|tsx|js|jsx)$"; then
+  exit 0
+fi
 
-case "$EXT" in
-  ts|tsx|js|jsx)
-    # toBeTruthy/toBeDefined in test files
-    if echo "$FILE_PATH" | grep -qE "\.(test|spec)\.(ts|tsx|js|jsx)$"; then
-      MATCH=$(grep -n "\.toBeTruthy()\|\.toBeDefined()" "$FILE_PATH" 2>/dev/null)
-      if [ -n "$MATCH" ]; then
-        FINDINGS="${FINDINGS}Weak assertion in $FILE_PATH: $MATCH. Test specific values instead. "
-      fi
-    fi
-    # catch-and-rethrow (catch { ...throw } with nothing meaningful between)
-    MATCH=$(grep -n "catch.*{" "$FILE_PATH" 2>/dev/null | head -3)
-    ;;
-  py)
-    # bare except: pass
-    MATCH=$(grep -n "except:$\|except Exception:$" "$FILE_PATH" 2>/dev/null)
-    if [ -n "$MATCH" ]; then
-      NEXT=$(grep -A1 "except" "$FILE_PATH" 2>/dev/null | grep -c "pass\|raise")
-      if [ "$NEXT" -gt 0 ]; then
-        FINDINGS="${FINDINGS}Bare except with pass/raise in $FILE_PATH. "
-      fi
-    fi
-    ;;
-esac
+MATCH=$(grep -n "\.toBeTruthy()\|\.toBeDefined()" "$FILE_PATH" 2>/dev/null)
+if [ -z "$MATCH" ]; then
+  exit 0
+fi
 
-if [ -n "$FINDINGS" ]; then
-  cat <<EOF
+cat <<EOF
 {
   "continue": true,
-  "systemMessage": "Slop detected: ${FINDINGS}"
+  "systemMessage": "Slop detected: weak assertion in $FILE_PATH:\n$MATCH\n\nTest specific values, not truthiness. See guardrails/test-slop.md."
 }
 EOF
-fi
-
 exit 0

package/hooks/uv-out-best.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# UV Suite helper: print the content of the best-matching artifact across sessions —
+# current session, else newest prior session, else legacy flat. A session-aware
+# drop-in for `cat uv-out/<X>` in skill preloads.
+#
+# Usage: uv-out-best.sh <relative-glob> [headLines]
+#   e.g. uv-out-best.sh map-codebase.md 100
+
+GLOB="$1"; HEAD="${2:-0}"
+[ -z "$GLOB" ] && exit 1
+
+# uv-out-collect.sh ranks current -> prior -> legacy; take the first path (field 4).
+FIRST=$("$(dirname "$0")/uv-out-collect.sh" "$GLOB" 2>/dev/null | head -1 | cut -f4)
+[ -z "$FIRST" ] || [ ! -f "$FIRST" ] && exit 1
+
+if [ "$HEAD" -gt 0 ] 2>/dev/null; then
+  head -n "$HEAD" "$FIRST"
+else
+  cat "$FIRST"
+fi

package/hooks/uv-out-collect.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# UV Suite helper: list an artifact across sessions for "prefer current, allow prior".
+# Usage: uv-out-collect.sh <relative-glob>      e.g.  specs/*.md   or   map-codebase.md
+#
+# Prints tab-separated lines, current session first, then other sessions
+# (newest session first), then legacy flat uv-out/ files:
+#   CURRENT  <session-name>  <YYYY-MM-DD>  <path>
+#   PRIOR    <session-name>  <YYYY-MM-DD>  <path>
+#   LEGACY   -               <YYYY-MM-DD>  <path>
+# A skill shows these and asks the user which to use (default: the CURRENT one,
+# else the newest PRIOR).
+
+GLOB="$1"
+[ -z "$GLOB" ] && exit 0
+
+ROOT="${CLAUDE_PROJECT_DIR:-.}"
+STATE_DIR="$ROOT/.uv-suite-state"
+SESS_META="$STATE_DIR/sessions"
+
+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
+
+# Human label for a session id: its name from the meta json, else the short id.
+label_for() {
+  local sid="$1" meta="$SESS_META/$1.json" name=""
+  if [ -f "$meta" ] && command -v jq >/dev/null 2>&1; then
+    name=$(jq -r '.name // ""' "$meta" 2>/dev/null)
+  fi
+  [ -n "$name" ] && printf '%s' "$name" || printf '%s' "${sid:0:8}"
+}
+
+emit() { # kind  session-label  path
+  [ -e "$3" ] || return 0
+  local d
+  d=$(date -r "$3" +%Y-%m-%d 2>/dev/null || echo "-")
+  printf '%s\t%s\t%s\t%s\n' "$1" "$2" "$d" "$3"
+}
+
+# Current session
+if [ -n "$SID" ]; then
+  for f in uv-out/sessions/"$SID"/$GLOB; do emit CURRENT "$(label_for "$SID")" "$f"; done
+fi
+# Other sessions, newest dir first
+for d in $(ls -dt uv-out/sessions/*/ 2>/dev/null); do
+  s=$(basename "$d")
+  [ "$s" = "$SID" ] && continue
+  for f in ${d}$GLOB; do emit PRIOR "$(label_for "$s")" "$f"; done
+done
+# Legacy flat layout (pre-session-scoping)
+for f in uv-out/$GLOB; do emit LEGACY "-" "$f"; done

package/hooks/uv-out-notify.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# UV Suite Hook: Surface the uv-out/ artifact path after a skill run.
+# Event: Stop
+# When a UV Suite skill writes artifacts to uv-out/, the writing happens inside a
+# forked sub-agent whose transcript the user never sees. This hook runs when control
+# returns to the main loop and prints the path so the user knows where output landed.
+
+[ -d uv-out ] || exit 0
+
+# Files written in the ~2 min covering the run that just finished.
+RECENT=$(find uv-out -type f -mmin -2 2>/dev/null | sort)
+[ -z "$RECENT" ] && exit 0
+
+LIST=$(echo "$RECENT" | sed 's/^/  /' | sed 's/$/\\n/' | tr -d '\n')
+
+# Name the session if these artifacts are session-scoped (uv-out/sessions/<sid>/...).
+SID=$(echo "$RECENT" | sed -n 's#^uv-out/sessions/\([^/]*\)/.*#\1#p' | head -1)
+HEADER="UV Suite output written to:"
+[ -n "$SID" ] && HEADER="UV Suite output (session ${SID}) written to:"
+
+cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "${HEADER}\n${LIST}"
+}
+EOF
+
+exit 0

package/hooks/uv-out-pointer.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# UV Suite helper: maintain a stable flat pointer into the current session's output.
+# Fixed-path consumers (/commit, /ship read uv-out/review-state.md and uv-out/qa-state.md)
+# keep working while the real artifact lives under uv-out/sessions/<sid>/.
+#
+# Usage: uv-out-pointer.sh <flat-name> <session-relative-target>
+#   e.g. uv-out-pointer.sh review-state.md review/state.md
+# Creates  uv-out/<flat-name>  ->  current/<session-relative-target>
+# (uv-out/current is the symlink to sessions/<sid>/ maintained by uv-out-session.sh).
+
+FLAT="$1"; TARGET="$2"
+[ -z "$FLAT" ] || [ -z "$TARGET" ] && exit 0
+
+mkdir -p uv-out
+ln -sfn "current/$TARGET" "uv-out/$FLAT" 2>/dev/null || true
+printf 'uv-out/%s -> current/%s\n' "$FLAT" "$TARGET"

package/hooks/uv-out-session.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# UV Suite helper: resolve (and create) the current session's uv-out output dir.
+# Prints the dir path (CWD-relative) on stdout so skills can namespace artifacts
+# by session — you can tell which session produced which artifact.
+#
+# Session id resolution mirrors session-start.sh:
+#   UVS_SESSION_ID env (set by uv.sh) → .uv-suite-state/current-session.txt → "no-session"
+
+ROOT="${CLAUDE_PROJECT_DIR:-.}"
+STATE_DIR="$ROOT/.uv-suite-state"
+
+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" ] && SID="no-session"
+
+OUT="uv-out/sessions/$SID"
+mkdir -p "$OUT"
+
+# Convenience pointer to the active session's output (symlink; ignore failure).
+ln -sfn "sessions/$SID" "uv-out/current" 2>/dev/null || true
+
+printf '%s\n' "$OUT"

package/hooks/watchtower-notify.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# UV Suite Hook Helper: Notify Watchtower of an approval request.
+# Fires on the Notification hook event (e.g. Claude is waiting for the user
+# to approve a tool call). Non-blocking. Fails silently if server not running.
+#
+# Usage from hook config (Notification event):
+#   "command": ".claude/hooks/watchtower-notify.sh"
+# Hook input JSON arrives via stdin from Claude Code.
+
+INPUT=$(cat)
+WATCHTOWER_URL="${UVS_WATCHTOWER_URL:-http://localhost:4200}"
+
+STATE_DIR="${CLAUDE_PROJECT_DIR:-.}/.uv-suite-state"
+
+# Resolve UVS session id: env first, then current-session pointer
+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
+
+PAYLOAD=""
+if command -v jq >/dev/null 2>&1; then
+  PAYLOAD=$(echo "$INPUT" | jq -c --arg sid "$SID" '
+    {
+      session_id: $sid,
+      tool_name: (.tool_name // ""),
+      command:   (.tool_input.command // .message // ""),
+      request:   .
+    }' 2>/dev/null)
+fi
+
+# Fallback when jq is missing or produced nothing usable
+if [ -z "$PAYLOAD" ] || [ "$PAYLOAD" = "null" ]; then
+  TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4)
+  PAYLOAD=$(printf '{"session_id":"%s","tool_name":"%s","command":"","request":%s}' \
+    "$SID" "$TOOL_NAME" "$INPUT")
+fi
+
+curl -s -X POST "$WATCHTOWER_URL/approvals" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  --max-time 2 \
+  &>/dev/null &
+
+exit 0

package/hooks/watchtower-send.sh

@@ -39,6 +39,10 @@ if command -v jq >/dev/null 2>&1; then
         session_purpose:  ($m[0].purpose // ""),
         session_priority: ($m[0].priority // ""),
         persona:          ($m[0].persona // ""),
+        git_worktree:           ($m[0].git_worktree // ""),
+        git_branch:             ($m[0].git_branch // ""),
+        git_main_repo:          ($m[0].git_main_repo // ""),
+        git_is_linked_worktree: ($m[0].git_is_linked_worktree // false),
         _hook_ts: now
       }' 2>/dev/null)
   else