uv-suite 0.26.2 → 0.26.4

package/bin/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 
-const { execSync, spawn } = require('child_process');
-const path = require('path');
-const fs = require('fs');
+const { execSync, spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const crypto = require("crypto");
+const readline = require("readline");
 
-const UV_SUITE_DIR = path.resolve(__dirname, '..');
+const UV_SUITE_DIR = path.resolve(__dirname, "..");
 const args = process.argv.slice(2);
 const command = args[0];
-const pkg = require(path.join(UV_SUITE_DIR, 'package.json'));
+const pkg = require(path.join(UV_SUITE_DIR, "package.json"));
 
-const PERSONAS = ['spike', 'sport', 'pro', 'professional', 'auto'];
-const TOOLS = ['claude', 'codex'];
+const PERSONAS = ["spike", "sport", "pro", "professional", "auto"];
+const TOOLS = ["claude", "codex"];
 
 function usage() {
   console.log(`
@@ -57,208 +59,333 @@ function info() {
 }
 
 function install() {
-  const installScript = path.join(UV_SUITE_DIR, 'install.sh');
+  const installScript = path.join(UV_SUITE_DIR, "install.sh");
   if (!fs.existsSync(installScript)) {
-    console.error('Error: install.sh not found at', installScript);
+    console.error("Error: install.sh not found at", installScript);
     process.exit(1);
   }
-  const installArgs = args.slice(1).join(' ');
+  const installArgs = args.slice(1).join(" ");
   try {
-    execSync(`bash "${installScript}" ${installArgs}`, { stdio: 'inherit' });
+    execSync(`bash "${installScript}" ${installArgs}`, { stdio: "inherit" });
   } catch (e) {
     process.exit(e.status || 1);
   }
 }
 
 function normPersona(p) {
-  if (p === 'pro' || p === 'professional') return 'professional';
+  if (p === "pro" || p === "professional") return "professional";
   if (PERSONAS.includes(p)) return p;
   return null;
 }
 
 function personaLabel(p) {
   const labels = {
-    spike: 'Spike — research & docs (Opus, max)',
-    sport: 'Sport — lightweight (Sonnet, high)',
-    professional: 'Professional — full rigor (all hooks, all guardrails)',
-    auto: 'Auto — autonomous (max, everything approved)',
+    spike: "Spike — research & docs (Opus, max)",
+    sport: "Sport — lightweight (Sonnet, high)",
+    professional: "Professional — full rigor (all hooks, all guardrails)",
+    auto: "Auto — autonomous (max, everything approved)",
   };
   return labels[p] || p;
 }
 
-function ensureInstalled(persona) {
-  const hooksDir = path.resolve('.claude/hooks');
-  const personasDir = path.resolve('.claude/personas');
-  const needsInstall = !fs.existsSync(personasDir) || !fs.existsSync(hooksDir);
-
-  if (needsInstall) {
-    console.log('UV Suite not installed in this project. Installing core files...');
-    console.log('');
-
-    // Fast install: copy essential files directly (no pip, no brew, no slow stuff)
-    const srcDir = UV_SUITE_DIR;
-    const targetDir = path.resolve('.claude');
-
-    // Create directories
-    for (const dir of ['agents', 'skills', 'hooks', 'rules', 'personas']) {
-      fs.mkdirSync(path.join(targetDir, dir), { recursive: true });
-    }
+// Sync package-owned files (hooks, skills, personas, agents, optional guardrails)
+// from the installed npm package into the project's .claude/. Idempotent — runs
+// every launch so users on older versions pick up new hooks and slash commands
+// after `npm install -g uv-suite@latest` without needing `uvs install` again.
+// settings.json is preserved if it exists (user customizations).
+function syncPackageFiles(persona) {
+  const srcDir = UV_SUITE_DIR;
+  const targetDir = path.resolve(".claude");
+  const hooksDir = path.join(targetDir, "hooks");
+  const personasDir = path.join(targetDir, "personas");
+  const wasFreshInstall =
+    !fs.existsSync(personasDir) || !fs.existsSync(hooksDir);
+
+  for (const dir of ["agents", "skills", "hooks", "rules", "personas"]) {
+    fs.mkdirSync(path.join(targetDir, dir), { recursive: true });
+  }
 
-    // Copy agents
-    const agentsSrc = path.join(srcDir, 'agents', 'claude-code');
-    if (fs.existsSync(agentsSrc)) {
-      for (const f of fs.readdirSync(agentsSrc)) {
-        fs.copyFileSync(path.join(agentsSrc, f), path.join(targetDir, 'agents', f));
-      }
+  const agentsSrc = path.join(srcDir, "agents", "claude-code");
+  if (fs.existsSync(agentsSrc)) {
+    for (const f of fs.readdirSync(agentsSrc)) {
+      fs.copyFileSync(
+        path.join(agentsSrc, f),
+        path.join(targetDir, "agents", f),
+      );
     }
+  }
 
-    // Copy hooks
-    const hooksSrc = path.join(srcDir, 'hooks');
-    if (fs.existsSync(hooksSrc)) {
-      for (const f of fs.readdirSync(hooksSrc)) {
-        const dest = path.join(targetDir, 'hooks', f);
-        fs.copyFileSync(path.join(hooksSrc, f), dest);
-        fs.chmodSync(dest, 0o755);
-      }
+  const hooksSrc = path.join(srcDir, "hooks");
+  if (fs.existsSync(hooksSrc)) {
+    for (const f of fs.readdirSync(hooksSrc)) {
+      const dest = path.join(targetDir, "hooks", f);
+      fs.copyFileSync(path.join(hooksSrc, f), dest);
+      fs.chmodSync(dest, 0o755);
     }
+  }
 
-    // Copy skills
-    const skillsSrc = path.join(srcDir, 'skills');
-    if (fs.existsSync(skillsSrc)) {
-      for (const d of fs.readdirSync(skillsSrc)) {
-        const skillFile = path.join(skillsSrc, d, 'SKILL.md');
-        if (fs.existsSync(skillFile)) {
-          const destDir = path.join(targetDir, 'skills', d);
-          fs.mkdirSync(destDir, { recursive: true });
-          fs.copyFileSync(skillFile, path.join(destDir, 'SKILL.md'));
-        }
+  const skillsSrc = path.join(srcDir, "skills");
+  if (fs.existsSync(skillsSrc)) {
+    for (const d of fs.readdirSync(skillsSrc)) {
+      const skillFile = path.join(skillsSrc, d, "SKILL.md");
+      if (fs.existsSync(skillFile)) {
+        const destDir = path.join(targetDir, "skills", d);
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.copyFileSync(skillFile, path.join(destDir, "SKILL.md"));
       }
     }
+  }
 
-    // Copy guardrails (for professional and auto)
-    if (persona === 'professional' || persona === 'auto') {
-      const guardSrc = path.join(srcDir, 'guardrails');
-      if (fs.existsSync(guardSrc)) {
-        for (const f of fs.readdirSync(guardSrc)) {
-          fs.copyFileSync(path.join(guardSrc, f), path.join(targetDir, 'rules', f));
-        }
+  if (persona === "professional" || persona === "auto") {
+    const guardSrc = path.join(srcDir, "guardrails");
+    if (fs.existsSync(guardSrc)) {
+      for (const f of fs.readdirSync(guardSrc)) {
+        fs.copyFileSync(
+          path.join(guardSrc, f),
+          path.join(targetDir, "rules", f),
+        );
       }
     }
+  }
 
-    // Copy personas
-    const personasSrc = path.join(srcDir, 'personas');
-    if (fs.existsSync(personasSrc)) {
-      for (const f of fs.readdirSync(personasSrc)) {
-        fs.copyFileSync(path.join(personasSrc, f), path.join(targetDir, 'personas', f));
-      }
+  const personasSrc = path.join(srcDir, "personas");
+  if (fs.existsSync(personasSrc)) {
+    for (const f of fs.readdirSync(personasSrc)) {
+      fs.copyFileSync(
+        path.join(personasSrc, f),
+        path.join(targetDir, "personas", f),
+      );
     }
+  }
 
-    // Set settings.json from persona
-    const personaFile = path.join(targetDir, 'personas', `${persona}.json`);
-    const settingsFile = path.join(targetDir, 'settings.json');
-    if (fs.existsSync(personaFile) && !fs.existsSync(settingsFile)) {
-      fs.copyFileSync(personaFile, settingsFile);
-    }
+  // settings.json is user-owned. Only seed it on fresh install.
+  const personaFile = path.join(targetDir, "personas", `${persona}.json`);
+  const settingsFile = path.join(targetDir, "settings.json");
+  if (
+    wasFreshInstall &&
+    fs.existsSync(personaFile) &&
+    !fs.existsSync(settingsFile)
+  ) {
+    fs.copyFileSync(personaFile, settingsFile);
+  }
 
+  if (wasFreshInstall) {
+    console.log(
+      "UV Suite not installed in this project. Installing core files...",
+    );
     console.log(`  Installed: agents, skills, hooks, guardrails, personas`);
-    console.log('');
+    console.log("");
+  }
+}
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function normalizeKind(s) {
+  const v = (s || "").toLowerCase().trim();
+  if (["l", "long", "long-running"].includes(v)) return "long-running";
+  if (["o", "outcome"].includes(v)) return "outcome";
+  return "";
+}
+
+function normalizePriority(s) {
+  const v = (s || "").toLowerCase().trim();
+  if (["l", "low"].includes(v)) return "low";
+  if (["m", "med", "medium"].includes(v)) return "med";
+  if (["h", "high"].includes(v)) return "high";
+  return "";
+}
+
+// Generate a UVS_SESSION_ID, prompt for metadata (name/kind/purpose/priority),
+// write it to .uv-suite-state/sessions/<sid>.json, and return the id + name.
+// Skipping (Enter) leaves a field empty; the session-label-nag.sh hook will
+// remind the user to run /session-init mid-flight.
+async function setupSession(persona) {
+  const projectDir = process.cwd();
+  const stateDir = path.join(projectDir, ".uv-suite-state");
+  const sessionsDir = path.join(stateDir, "sessions");
+  fs.mkdirSync(sessionsDir, { recursive: true });
+
+  const sid = crypto.randomUUID();
+  let name = "";
+  let kind = "";
+  let purpose = "";
+  let priority = "";
+
+  if (process.stdin.isTTY && !process.env.UVS_NO_PROMPT) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    console.log("");
+    console.log("Label this session (Enter to skip — you'll be reminded):");
+    name = (await prompt(rl, "  name:                     ")).trim();
+    const kindRaw = await prompt(rl, "  kind [long/outcome]:      ");
+    purpose = (await prompt(rl, "  purpose:                  ")).trim();
+    const priorityRaw = await prompt(rl, "  priority [low/med/high]:  ");
+    rl.close();
+    kind = normalizeKind(kindRaw);
+    priority = normalizePriority(priorityRaw);
   }
+
+  const meta = {
+    uvs_session_id: sid,
+    name,
+    kind,
+    purpose,
+    priority,
+    persona,
+    cwd: projectDir,
+    started_at: Math.floor(Date.now() / 1000),
+  };
+  fs.writeFileSync(
+    path.join(sessionsDir, `${sid}.json`),
+    JSON.stringify(meta, null, 2),
+  );
+  fs.writeFileSync(path.join(stateDir, "current-session.txt"), sid);
+
+  return { sid, name };
+}
+
+// Backwards-compat shim — older code in this file still references this name.
+function ensureInstalled(persona) {
+  syncPackageFiles(persona);
 }
 
-function launchClaude(persona, extra) {
-  ensureInstalled(persona);
-  const settings = path.resolve('.claude/personas', `${persona}.json`);
+async function launchClaude(persona, extra) {
+  syncPackageFiles(persona);
+  const settings = path.resolve(".claude/personas", `${persona}.json`);
   if (!fs.existsSync(settings)) {
-    console.error(`Error: installation failed. Run 'uvs install --persona ${persona}' manually.`);
+    console.error(
+      `Error: installation failed. Run 'uvs install --persona ${persona}' manually.`,
+    );
     process.exit(1);
   }
+  const { sid, name } = await setupSession(persona);
+  console.log("");
   console.log(`UV Suite | Claude Code | ${personaLabel(persona)}`);
-  console.log('');
-  const child = spawn('claude', ['--settings', settings, ...extra], { stdio: 'inherit' });
-  child.on('exit', (code) => process.exit(code || 0));
+  console.log(`Session: ${sid.slice(0, 8)}${name ? " — " + name : ""}`);
+  console.log("");
+  const child = spawn("claude", ["--settings", settings, ...extra], {
+    stdio: "inherit",
+    env: { ...process.env, UVS_SESSION_ID: sid },
+  });
+  child.on("exit", (code) => process.exit(code || 0));
 }
 
-function launchCodex(persona, extra) {
+async function launchCodex(persona, extra) {
   const approvalMap = {
-    spike: ['--model', 'o3', '--approval-mode', 'suggest'],
-    sport: ['--approval-mode', 'auto-edit'],
-    professional: ['--approval-mode', 'suggest'],
-    auto: ['--approval-mode', 'full-auto'],
+    spike: ["--model", "o3", "--approval-mode", "suggest"],
+    sport: ["--approval-mode", "auto-edit"],
+    professional: ["--approval-mode", "suggest"],
+    auto: ["--approval-mode", "full-auto"],
   };
-  const codexArgs = approvalMap[persona] || ['--approval-mode', 'suggest'];
+  const codexArgs = approvalMap[persona] || ["--approval-mode", "suggest"];
+  const { sid, name } = await setupSession(persona);
+  console.log("");
   console.log(`UV Suite | Codex | ${personaLabel(persona)}`);
-  console.log('');
-  const child = spawn('codex', [...codexArgs, ...extra], { stdio: 'inherit' });
-  child.on('exit', (code) => process.exit(code || 0));
+  console.log(`Session: ${sid.slice(0, 8)}${name ? " — " + name : ""}`);
+  console.log("");
+  const child = spawn("codex", [...codexArgs, ...extra], {
+    stdio: "inherit",
+    env: { ...process.env, UVS_SESSION_ID: sid },
+  });
+  child.on("exit", (code) => process.exit(code || 0));
 }
 
 function watch() {
-  const serverScript = path.join(UV_SUITE_DIR, 'watchtower', 'server.js');
+  const serverScript = path.join(UV_SUITE_DIR, "watchtower", "server.js");
   if (!fs.existsSync(serverScript)) {
-    console.error('Error: watchtower server not found at', serverScript);
+    console.error("Error: watchtower server not found at", serverScript);
     process.exit(1);
   }
 
-  const bg = args.includes('--bg') || args.includes('--background');
-  console.log('UV Suite Watchtower starting...');
-  console.log('Dashboard: http://localhost:' + (process.env.UVS_WATCHTOWER_PORT || 4200));
-  console.log('');
+  const bg = args.includes("--bg") || args.includes("--background");
+  console.log("UV Suite Watchtower starting...");
+  console.log(
+    "Dashboard: http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200),
+  );
+  console.log("");
 
   if (bg) {
-    const child = spawn('node', [serverScript], {
-      stdio: 'ignore',
+    const child = spawn("node", [serverScript], {
+      stdio: "ignore",
       detached: true,
     });
     child.unref();
     console.log(`Running in background (PID: ${child.pid})`);
-    console.log('Stop with: kill ' + child.pid);
+    console.log("Stop with: kill " + child.pid);
 
     // Open browser
-    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    spawn(opener, ['http://localhost:' + (process.env.UVS_WATCHTOWER_PORT || 4200)], { stdio: 'ignore' });
+    const opener =
+      process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+          ? "start"
+          : "xdg-open";
+    spawn(
+      opener,
+      ["http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200)],
+      { stdio: "ignore" },
+    );
   } else {
     // Foreground — open browser after a short delay
     setTimeout(() => {
-      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      spawn(opener, ['http://localhost:' + (process.env.UVS_WATCHTOWER_PORT || 4200)], { stdio: 'ignore' });
+      const opener =
+        process.platform === "darwin"
+          ? "open"
+          : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+      spawn(
+        opener,
+        ["http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200)],
+        { stdio: "ignore" },
+      );
     }, 1000);
 
-    const child = spawn('node', [serverScript], { stdio: 'inherit' });
-    child.on('exit', (code) => process.exit(code || 0));
+    const child = spawn("node", [serverScript], { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code || 0));
   }
 }
 
 // --- Parse and route ---
 
-if (!command || command === '--help' || command === '-h') {
+if (!command || command === "--help" || command === "-h") {
   usage();
   process.exit(0);
 }
 
-if (command === 'watch') {
-  watch();
-} else if (command === 'install') {
-  install();
-} else if (command === 'info') {
-  info();
-} else if (TOOLS.includes(command)) {
-  // uv claude pro, uv codex auto
-  const persona = normPersona(args[1] || 'pro');
-  if (!persona) {
-    console.error(`Unknown persona: ${args[1]}`);
-    console.error('Available: spike, sport, pro, auto');
+(async () => {
+  if (command === "watch") {
+    watch();
+  } else if (command === "install") {
+    install();
+  } else if (command === "info") {
+    info();
+  } else if (TOOLS.includes(command)) {
+    // uvs claude pro, uvs codex auto
+    const persona = normPersona(args[1] || "pro");
+    if (!persona) {
+      console.error(`Unknown persona: ${args[1]}`);
+      console.error("Available: spike, sport, pro, auto");
+      process.exit(1);
+    }
+    const extra = args.slice(2);
+    if (command === "claude") await launchClaude(persona, extra);
+    else await launchCodex(persona, extra);
+  } else if (normPersona(command)) {
+    // uvs pro (shorthand for uvs claude pro)
+    const persona = normPersona(command);
+    const extra = args.slice(1);
+    await launchClaude(persona, extra);
+  } else {
+    console.error(`Unknown command: ${command}`);
+    usage();
     process.exit(1);
   }
-  const extra = args.slice(2);
-  if (command === 'claude') launchClaude(persona, extra);
-  else launchCodex(persona, extra);
-} else if (normPersona(command)) {
-  // uv pro (shorthand for uv claude pro)
-  const persona = normPersona(command);
-  const extra = args.slice(1);
-  launchClaude(persona, extra);
-} else {
-  console.error(`Unknown command: ${command}`);
-  usage();
+})().catch((err) => {
+  console.error(err);
   process.exit(1);
-}
+});

package/hooks/checkpoint-helper.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# UV Suite helper: locate per-session checkpoint paths and print metadata.
+# Used by the /checkpoint and /restore slash commands.
+#
+# Usage:
+#   checkpoint-helper.sh dir       # ensure + print the dir for current session
+#   checkpoint-helper.sh meta      # print session metadata as shell-eval'able lines
+#   checkpoint-helper.sh frontmatter  # YAML frontmatter to embed at the top of a checkpoint
+#   checkpoint-helper.sh latest    # cat the latest checkpoint for current session (with fallback)
+#   checkpoint-helper.sh list      # list all sessions that have checkpoints, newest first
+
+resolve_paths() {
+  PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  STATE_DIR="$PROJECT_DIR/.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
+  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"
+}
+
+print_meta_field() {
+  # $1 = field name; reads from $META_FILE; empty if missing
+  [ -z "$META_FILE" ] || [ ! -f "$META_FILE" ] && { echo ""; return; }
+  if command -v jq >/dev/null 2>&1; then
+    jq -r --arg k "$1" '.[$k] // ""' "$META_FILE" 2>/dev/null
+  else
+    grep -o "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$META_FILE" | head -1 | sed "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\(.*\)\"/\1/"
+  fi
+}
+
+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
+    ;;
+  meta)
+    echo "uvs_session_id=${SID:-}"
+    echo "session_name=$(print_meta_field name)"
+    echo "session_kind=$(print_meta_field kind)"
+    echo "session_purpose=$(print_meta_field purpose)"
+    echo "session_priority=$(print_meta_field priority)"
+    echo "persona=$(print_meta_field persona)"
+    ;;
+  frontmatter)
+    NAME=$(print_meta_field name)
+    KIND=$(print_meta_field kind)
+    PURPOSE=$(print_meta_field purpose)
+    PRIORITY=$(print_meta_field priority)
+    PERSONA=$(print_meta_field persona)
+    NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    cat <<EOF
+---
+uvs_session_id: ${SID:-}
+session_name: ${NAME}
+session_kind: ${KIND}
+session_purpose: ${PURPOSE}
+session_priority: ${PRIORITY}
+persona: ${PERSONA}
+checkpoint_at: ${NOW}
+---
+EOF
+    ;;
+  latest)
+    if [ -n "$SESSION_CP_DIR" ] && [ -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)"
+      echo
+      cat "$CHECKPOINTS_ROOT/latest.md"
+    else
+      echo "No checkpoint found at $CHECKPOINTS_ROOT. Run /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=""
+      if [ -f "$cp_meta" ]; then
+        if command -v jq >/dev/null 2>&1; then
+          cp_name=$(jq -r '.name // ""' "$cp_meta" 2>/dev/null)
+          cp_priority=$(jq -r '.priority // ""' "$cp_meta" 2>/dev/null)
+        else
+          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
+      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"
+      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)
+      echo "  legacy   $ts  (pre-metadata global latest.md)"
+    fi
+    ;;
+  *)
+    echo "Usage: checkpoint-helper.sh [dir|meta|frontmatter|latest|list]"
+    exit 1
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "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/checkpoint/SKILL.md

@@ -3,7 +3,8 @@ name: checkpoint
 description: >
   Save a checkpoint of the current session — what was done, key decisions, current state,
   and what's next. Use before ending a session, before /compact, or at any natural breakpoint.
-  The next session auto-loads the latest checkpoint.
+  Checkpoints are stored per-session under uv-out/checkpoints/<session-id>/, so concurrent
+  terminals don't clobber each other. /restore picks up the latest for the current session.
 argument-hint: "[optional-label]"
 user-invocable: true
 allowed-tools:
@@ -12,39 +13,51 @@ allowed-tools:
   - 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 *)
 ---
 
-## Resolve checkpoint directory
+## Resolve session and checkpoint directory
 
-Anchor checkpoints to `$CLAUDE_PROJECT_DIR` (or the git repo root, or the current
-working dir as a last resort) so `/checkpoint` and `/restore` always agree, no matter
-which subdirectory the session was launched from.
-
-!`DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/uv-out/checkpoints"; mkdir -p "$DIR"; echo "$DIR"`
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh dir`
 
 Use the absolute path printed above as `<checkpoint-dir>` for every file path below.
+The directory is per-session — two `uv` launches in the same repo write to
+different folders, so checkpoints don't collide.
+
+## Session metadata
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh meta`
+
+## Frontmatter to embed at the top of the checkpoint
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh frontmatter`
 
 ## Write a checkpoint
 
-Write a file named `<checkpoint-dir>/YYYY-MM-DD-HHMM.md` using the current timestamp.
+Write a file named `<checkpoint-dir>/YYYY-MM-DD-HHMM.md` using the current
+timestamp. **Begin the file with the YAML frontmatter block printed above
+exactly as shown** — `/restore` parses these fields when picking which
+checkpoint to load.
 
-Also write/overwrite `<checkpoint-dir>/latest.md` with the same content, so the next
-session's `/restore` always finds the freshest state.
+Also write/overwrite `<checkpoint-dir>/latest.md` with the same content,
+so the next session's `/restore` always finds the freshest state for this
+session.
 
 ## Label
 
 $ARGUMENTS
 
-If a label was provided, include it in the filename: `<checkpoint-dir>/YYYY-MM-DD-HHMM-[label].md`
-
-## What to capture
+If a label was provided, include it in the filename:
+`<checkpoint-dir>/YYYY-MM-DD-HHMM-[label].md`
 
-Review the full conversation so far and write a structured checkpoint with these exact sections:
+## Body structure (after the frontmatter)
 
 ```markdown
 # Checkpoint: [date] [time] [label if provided]
@@ -88,5 +101,5 @@ Review the full conversation so far and write a structured checkpoint with these
 
 - Be specific. "Worked on auth" is useless. "Added JWT refresh token rotation with 7-day expiry" is useful.
 - Capture WHY decisions were made, not just what. The next session needs the rationale.
-- Keep it under 80 lines. This isn't a novel — it's a handoff.
-- Every checkpoint overwrites `latest.md` so the next session always finds the freshest state.
+- Keep the body under 80 lines. The frontmatter is required and not counted.
+- Always include the YAML frontmatter — `/restore` reads it to pick the right checkpoint and to display session context.

package/skills/restore/SKILL.md

@@ -1,25 +1,55 @@
 ---
 name: restore
 description: >
-  Restore the latest checkpoint from a previous session. Shows what was done,
-  key decisions, current state, and what's next. Use at the start of a new session.
+  Restore the latest checkpoint for the current session — shows what was done,
+  key decisions, current state, and what's next. With no arguments, picks the
+  current `UVS_SESSION_ID`'s most recent checkpoint. Pass a session id prefix
+  or name to restore from a different session.
+argument-hint: "[<session-id-prefix> | <session-name> | list]"
 user-invocable: true
 allowed-tools:
   - Read(*)
   - Bash(ls *)
   - Bash(cat *)
   - Bash(grep *)
+  - Bash(find *)
   - Bash(git rev-parse *)
+  - Bash("$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh *)
 ---
 
-## Latest checkpoint
+## Available sessions with checkpoints
 
-!`DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/uv-out/checkpoints"; if [ -f "$DIR/latest.md" ]; then cat "$DIR/latest.md"; else echo "No checkpoint found at $DIR. Run /checkpoint to create one."; fi`
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh list`
 
-## All checkpoints
+(`*` marks the current session.)
 
-!`DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/uv-out/checkpoints"; if [ -d "$DIR" ]; then matches=$(ls -la "$DIR"/ 2>/dev/null | grep '\.md$' | tail -10); if [ -n "$matches" ]; then echo "$matches"; else echo "No checkpoints in $DIR"; fi; else echo "No checkpoints directory at $DIR"; fi`
+## Latest checkpoint for the current session
+
+!`"$CLAUDE_PROJECT_DIR"/.claude/hooks/checkpoint-helper.sh latest`
+
+## Argument
+
+$ARGUMENTS
 
 ## Instructions
 
-Read the checkpoint above. Summarize it to the user in 3-4 sentences: what was done, what's the current state, and what's next. Then ask: "Ready to pick up from here, or do you want to take a different direction?"
+1. **If `$ARGUMENTS` is empty or "latest"**: read the checkpoint shown above (the
+   current session's `latest.md`). Summarize it in 3-4 sentences: what was
+   done, current state, what's next. Then ask: "Ready to pick up from here, or
+   do you want to take a different direction?"
+
+2. **If `$ARGUMENTS` is "list"**: just show the user the available-sessions
+   list above and ask which one they want to restore.
+
+3. **If `$ARGUMENTS` looks like a session id prefix** (8-char hex / UUID-ish)
+   **or a session name**: match it against the list above. Read the
+   matching session's `latest.md` from
+   `<project>/uv-out/checkpoints/<full-session-id>/latest.md` using the Read
+   tool, then summarize as in (1).
+
+4. If no match is found, list the available sessions and ask the user to
+   pick one.
+
+When summarizing, include the session's name and purpose from the
+frontmatter at the top of the checkpoint — that's the context the next
+session needs to know what it's picking up.