uv-suite 0.28.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.28.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/watchtower/dashboard.html

@@ -409,6 +409,124 @@
     font-size: 12px;
     margin-left: 8px;
   }
+
+  /* Header buttons (snapshot, snapshots-list) */
+  .header-btn {
+    background: transparent;
+    color: var(--text-muted);
+    border: 1px solid var(--border);
+    border-radius: 7px;
+    height: 30px;
+    padding: 0 12px;
+    font-size: 13px;
+    font-family: inherit;
+    cursor: pointer;
+    transition: color 0.15s ease, border-color 0.15s ease, background-color 0.15s ease;
+  }
+  .header-btn:hover { color: var(--text); border-color: var(--text-dim); background: var(--surface); }
+  .header-btn.primary { background: var(--accent); color: var(--accent-contrast); border-color: var(--accent); }
+  .header-btn.primary:hover { opacity: 0.9; }
+  .header-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+  /* Snapshots modal overlay */
+  .modal-overlay {
+    position: fixed;
+    inset: 0;
+    background: rgba(0,0,0,0.45);
+    display: none;
+    align-items: center;
+    justify-content: center;
+    z-index: 100;
+  }
+  .modal-overlay.open { display: flex; }
+  .modal {
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    width: 720px;
+    max-width: 92vw;
+    max-height: 80vh;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+  }
+  .modal-header {
+    padding: 16px 20px;
+    border-bottom: 1px solid var(--border-subtle);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  .modal-header h2 { font-size: 16px; font-weight: 600; }
+  .modal-body { padding: 16px 20px; overflow-y: auto; flex: 1; }
+  .modal-close {
+    background: transparent;
+    color: var(--text-dim);
+    border: none;
+    font-size: 22px;
+    cursor: pointer;
+    line-height: 1;
+  }
+  .modal-close:hover { color: var(--text); }
+
+  .snapshot-list { display: flex; flex-direction: column; gap: 8px; }
+  .snapshot-row {
+    padding: 12px 14px;
+    border: 1px solid var(--border-subtle);
+    border-radius: 7px;
+    cursor: pointer;
+    transition: background-color 0.15s ease, border-color 0.15s ease;
+  }
+  .snapshot-row:hover { background: var(--surface); border-color: var(--text-dim); }
+  .snapshot-row .id { font-family: var(--font-mono); font-size: 12.5px; color: var(--text-muted); }
+  .snapshot-row .meta { display: flex; justify-content: space-between; align-items: center; }
+
+  .snapshot-detail .sess-row {
+    margin-bottom: 14px;
+    padding: 12px 14px;
+    border: 1px solid var(--border-subtle);
+    border-radius: 7px;
+  }
+  .snapshot-detail .sess-row .head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 6px;
+    gap: 8px;
+  }
+  .snapshot-detail .sess-row .name { font-weight: 600; }
+  .snapshot-detail .sess-row .preview {
+    color: var(--text-muted);
+    font-size: 12.5px;
+    line-height: 1.55;
+    white-space: pre-wrap;
+    max-height: 100px;
+    overflow-y: auto;
+  }
+  .snapshot-toast {
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    color: var(--text);
+    padding: 10px 14px;
+    border-radius: 7px;
+    font-size: 13px;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.25);
+    display: none;
+    z-index: 200;
+    max-width: 480px;
+  }
+  .snapshot-toast.show { display: block; }
+  .snapshot-toast pre {
+    margin-top: 6px;
+    padding: 8px;
+    background: var(--bg);
+    border-radius: 4px;
+    font-size: 11.5px;
+    overflow-x: auto;
+  }
 </style>
 </head>
 <body>
@@ -417,6 +535,8 @@
   <h1>UV Suite Watchtower</h1>
   <div class="meta">
     <div class="status"><span class="dot" id="statusDot"></span><span id="statusText">Connecting...</span></div>
+    <button class="header-btn primary" id="btnSnapshot" type="button" title="Snapshot every active session now">Snapshot all</button>
+    <button class="header-btn" id="btnSnapshotsList" type="button" title="Open the list of past snapshots">Snapshots…</button>
     <button class="theme-toggle" id="themeToggle" type="button" aria-label="Toggle theme" title="Toggle theme">
       <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
         <circle cx="12" cy="12" r="4"/>
@@ -459,6 +579,18 @@
   </div>
 </div>
 
+<div class="modal-overlay" id="snapshotsModal">
+  <div class="modal">
+    <div class="modal-header">
+      <h2 id="snapshotsModalTitle">Snapshots</h2>
+      <button class="modal-close" id="snapshotsModalClose" type="button" aria-label="Close">×</button>
+    </div>
+    <div class="modal-body" id="snapshotsModalBody"></div>
+  </div>
+</div>
+
+<div class="snapshot-toast" id="snapshotToast"></div>
+
 
 <script>
 const timeline = document.getElementById('timeline');
@@ -945,6 +1077,135 @@ mql.addEventListener('change', () => {
   if (!localStorage.getItem(THEME_KEY)) applyTheme(resolvedTheme());
 });
 
+// --- Snapshot + Restore UI ---
+const btnSnapshot = document.getElementById('btnSnapshot');
+const btnSnapshotsList = document.getElementById('btnSnapshotsList');
+const snapshotsModal = document.getElementById('snapshotsModal');
+const snapshotsModalTitle = document.getElementById('snapshotsModalTitle');
+const snapshotsModalBody = document.getElementById('snapshotsModalBody');
+const snapshotsModalClose = document.getElementById('snapshotsModalClose');
+const snapshotToast = document.getElementById('snapshotToast');
+
+function showToast(html, ms = 5000) {
+  snapshotToast.innerHTML = html;
+  snapshotToast.classList.add('show');
+  clearTimeout(showToast._t);
+  showToast._t = setTimeout(() => snapshotToast.classList.remove('show'), ms);
+}
+
+function openModal() { snapshotsModal.classList.add('open'); }
+function closeModal() { snapshotsModal.classList.remove('open'); }
+snapshotsModalClose.onclick = closeModal;
+snapshotsModal.onclick = (e) => { if (e.target === snapshotsModal) closeModal(); };
+
+btnSnapshot.onclick = async () => {
+  btnSnapshot.disabled = true;
+  btnSnapshot.textContent = 'Snapshotting…';
+  try {
+    const r = await fetch('/snapshots', { method: 'POST' });
+    if (!r.ok) throw new Error('snapshot request failed: ' + r.status);
+    const manifest = await r.json();
+    showToast(`Snapshot <strong>${escapeHtml(manifest.id)}</strong> captured: ${manifest.sessions.length} active session${manifest.sessions.length === 1 ? '' : 's'}.`);
+  } catch (err) {
+    showToast(`Snapshot failed: ${escapeHtml(err.message)}`);
+  } finally {
+    btnSnapshot.disabled = false;
+    btnSnapshot.textContent = 'Snapshot all';
+  }
+};
+
+btnSnapshotsList.onclick = async () => {
+  snapshotsModalTitle.textContent = 'Snapshots';
+  snapshotsModalBody.innerHTML = '<p style="color:var(--text-muted)">Loading…</p>';
+  openModal();
+  try {
+    const r = await fetch('/snapshots');
+    const list = await r.json();
+    if (!list.length) {
+      snapshotsModalBody.innerHTML = '<p style="color:var(--text-muted)">No snapshots yet. Click "Snapshot all" in the header to take one.</p>';
+      return;
+    }
+    const rows = list.map(s => `
+      <div class="snapshot-row" data-id="${escapeHtml(s.id)}">
+        <div class="meta">
+          <span class="id">${escapeHtml(s.id)}</span>
+          <span style="color:var(--text-muted); font-size:12.5px">${s.session_count} session${s.session_count === 1 ? '' : 's'}</span>
+        </div>
+        <div style="color:var(--text-dim); font-size:12px; margin-top:4px">${new Date(s.created_at).toLocaleString()}</div>
+      </div>
+    `).join('');
+    snapshotsModalBody.innerHTML = `<div class="snapshot-list">${rows}</div>`;
+    snapshotsModalBody.querySelectorAll('.snapshot-row').forEach(row => {
+      row.onclick = () => openSnapshotDetail(row.dataset.id);
+    });
+  } catch (err) {
+    snapshotsModalBody.innerHTML = `<p style="color:var(--danger)">Failed to load snapshots: ${escapeHtml(err.message)}</p>`;
+  }
+};
+
+async function openSnapshotDetail(id) {
+  snapshotsModalTitle.textContent = 'Snapshot ' + id;
+  snapshotsModalBody.innerHTML = '<p style="color:var(--text-muted)">Loading…</p>';
+  try {
+    const r = await fetch('/snapshots/' + encodeURIComponent(id));
+    if (!r.ok) throw new Error('snapshot not found');
+    const m = await r.json();
+    if (!m.sessions || m.sessions.length === 0) {
+      snapshotsModalBody.innerHTML = '<p style="color:var(--text-muted)">No active sessions were captured in this snapshot.</p>';
+      return;
+    }
+    const restoreAll = `<button class="header-btn primary" id="btnRestoreAll" type="button">Restore all (${m.sessions.length})</button>`;
+    const back = `<button class="header-btn" id="btnBackToSnapshots" type="button">← Back to list</button>`;
+    const sessions = m.sessions.map(s => `
+      <div class="sess-row" data-sid="${escapeHtml(s.uvs_session_id)}">
+        <div class="head">
+          <div>
+            <span class="name">${escapeHtml(s.name || '(unlabeled)')}</span>
+            <span style="color:var(--text-dim); font-size:12px; margin-left:8px">${escapeHtml((s.uvs_session_id || '').slice(0,8))}</span>
+            <span class="pill persona-${escapeHtml(s.persona || '')}" style="margin-left:6px">${escapeHtml(s.persona || '?')}</span>
+            ${s.priority ? `<span class="pill priority-${escapeHtml(s.priority)}">P:${escapeHtml(s.priority)}</span>` : ''}
+          </div>
+          <button class="header-btn restore-btn" type="button">Open in new terminal</button>
+        </div>
+        <div style="color:var(--text-dim); font-size:12px; margin-bottom:6px">${escapeHtml(s.cwd || '')}${s.purpose ? ' — ' + escapeHtml(s.purpose) : ''}</div>
+        <div class="preview">${s.summary_preview ? escapeHtml(s.summary_preview) : '<em style="color:var(--text-dim)">(no checkpoint summary yet)</em>'}</div>
+      </div>
+    `).join('');
+    snapshotsModalBody.innerHTML = `
+      <div style="display:flex; justify-content:space-between; margin-bottom:14px">${back}${restoreAll}</div>
+      <div class="snapshot-detail">${sessions}</div>
+    `;
+
+    document.getElementById('btnBackToSnapshots').onclick = () => btnSnapshotsList.onclick();
+    document.getElementById('btnRestoreAll').onclick = () => {
+      m.sessions.forEach(s => restoreSession(id, s.uvs_session_id));
+    };
+    snapshotsModalBody.querySelectorAll('.sess-row').forEach(row => {
+      row.querySelector('.restore-btn').onclick = () => restoreSession(id, row.dataset.sid);
+    });
+  } catch (err) {
+    snapshotsModalBody.innerHTML = `<p style="color:var(--danger)">Failed to load: ${escapeHtml(err.message)}</p>`;
+  }
+}
+
+async function restoreSession(snapshotId, sid) {
+  try {
+    const r = await fetch(`/snapshots/${encodeURIComponent(snapshotId)}/sessions/${encodeURIComponent(sid)}/restore`, { method: 'POST' });
+    const result = await r.json();
+    if (result.ok) {
+      showToast(`Opened new terminal for <strong>${escapeHtml(sid.slice(0,8))}</strong>.`);
+    } else {
+      // Fallback: show the copy-paste command
+      showToast(
+        `Couldn't auto-open a terminal on this platform (<code>${escapeHtml(result.platform)}</code>). Copy and run:<pre>${escapeHtml(result.command || '')}</pre>`,
+        12000,
+      );
+    }
+  } catch (err) {
+    showToast(`Restore failed: ${escapeHtml(err.message)}`);
+  }
+}
+
 connect();
 </script>
 </body>

package/watchtower/events.json

@@ -1 +1,74 @@
-[]
+[
+  {
+    "event_type": "PostToolUse",
+    "uvs_session_id": "snap-test-A",
+    "session_id": "cc-A",
+    "cwd": "/tmp/uvs-tierb-test",
+    "session_name": "snapshot test A",
+    "session_kind": "outcome",
+    "session_priority": "high",
+    "persona": "auto",
+    "tool_name": "Edit",
+    "_ts": 1778537691312,
+    "_id": "95a2a933-1f9e-4e0b-95fd-9e43fa8050a1"
+  },
+  {
+    "event_type": "PostToolUse",
+    "uvs_session_id": "snap-test-B",
+    "session_id": "cc-B",
+    "cwd": "/tmp/uvs-tierb-test",
+    "session_name": "snapshot test B",
+    "session_kind": "long-running",
+    "persona": "sport",
+    "tool_name": "Read",
+    "_ts": 1778537691332,
+    "_id": "0424ce0d-f8b5-4f7e-8ca2-60b23d8ebc11"
+  },
+  {
+    "event_type": "AutoCheckpoint",
+    "source_app": "uvs-tierb-test",
+    "cwd": "/tmp/uvs-tierb-test",
+    "uvs_session_id": "snap-test-A",
+    "session_id": "snap-test-A",
+    "session_name": "snapshot test A",
+    "session_kind": "outcome",
+    "session_priority": "high",
+    "persona": "auto",
+    "checkpoint_kind": "auto-semantic",
+    "checkpoint_path": "/tmp/uvs-tierb-test/uv-out/checkpoints/snap-test-A/auto-2026-05-11-2214-semantic.md",
+    "checkpoint_summary": "_(no conversation transcript available; only mechanical activity below)_",
+    "checkpoint_preview": "---\nuvs_session_id: snap-test-A\nsession_name: snapshot test A\nsession_kind: outcome\nsession_purpose: \nsession_priority: high\npersona: auto\ncheckpoint_at: 2026-05-11T22:14:51.348Z\ncheckpoint_kind: auto-semantic\ntranscript_messages: 0\ntool_calls_in_window: 1\n---\n# Auto-checkpoint (semantic): 2026-05-11T22:14:51.348Z\n\n## Summary\n\n_(no conversation transcript available; only mechanical activity below)_\n\n## Conversation\n\n_(no transcript content found; only mechanical activity captured below)_\n\n## Mechanical\n\n### Tool calls\n- 1× Edit\n\n## Git\n\n**Branch:** main\n\n**Status:**\n```\n?? .uv-suite-state/\n?? fakebin/\n?? parser-test.js\n?? tierB-test.js\n?? uv-out/\n```\n\n**Recent commits:**\n```\n09105d2 initial\n```\n",
+    "interval_minutes": 1,
+    "tool_calls_in_window": 1,
+    "transcript_messages": 0,
+    "_ts": 1778537691348,
+    "_id": "a5b91efb-8286-45eb-a98a-f6e51da816f4"
+  },
+  {
+    "event_type": "AutoCheckpoint",
+    "source_app": "uvs-tierb-test",
+    "cwd": "/tmp/uvs-tierb-test",
+    "uvs_session_id": "snap-test-B",
+    "session_id": "snap-test-B",
+    "session_name": "snapshot test B",
+    "session_kind": "long-running",
+    "session_priority": "",
+    "persona": "sport",
+    "checkpoint_kind": "auto-semantic",
+    "checkpoint_path": "/tmp/uvs-tierb-test/uv-out/checkpoints/snap-test-B/auto-2026-05-11-2214-semantic.md",
+    "checkpoint_summary": "_(no conversation transcript available; only mechanical activity below)_",
+    "checkpoint_preview": "---\nuvs_session_id: snap-test-B\nsession_name: snapshot test B\nsession_kind: long-running\nsession_purpose: \nsession_priority: \npersona: sport\ncheckpoint_at: 2026-05-11T22:14:51.451Z\ncheckpoint_kind: auto-semantic\ntranscript_messages: 0\ntool_calls_in_window: 1\n---\n# Auto-checkpoint (semantic): 2026-05-11T22:14:51.451Z\n\n## Summary\n\n_(no conversation transcript available; only mechanical activity below)_\n\n## Conversation\n\n_(no transcript content found; only mechanical activity captured below)_\n\n## Mechanical\n\n### Tool calls\n- 1× Read\n\n## Git\n\n**Branch:** main\n\n**Status:**\n```\n?? .uv-suite-state/\n?? fakebin/\n?? parser-test.js\n?? tierB-test.js\n?? uv-out/\n```\n\n**Recent commits:**\n```\n09105d2 initial\n```\n",
+    "interval_minutes": 1,
+    "tool_calls_in_window": 1,
+    "transcript_messages": 0,
+    "_ts": 1778537691451,
+    "_id": "6f09091b-1bf1-4bc8-bb02-2d6ab7badbb1"
+  },
+  {
+    "event_type": "SnapshotTaken",
+    "snapshot_id": "2026-05-11-22-1451",
+    "session_count": 2,
+    "_ts": 1778537691524,
+    "_id": "e2a54e27-92de-4f18-aa2c-6044d1adde7e"
+  }
+]

package/watchtower/server.js

@@ -9,6 +9,7 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const autoCheckpointRunner = require("./auto-checkpoint-runner");
+const snapshotManager = require("./snapshot-manager");
 
 const PORT = process.env.UVS_WATCHTOWER_PORT || 4200;
 const DATA_FILE = path.join(__dirname, "events.json");
@@ -120,6 +121,68 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  // POST /snapshots — take a snapshot of every active session
+  if (req.method === "POST" && req.url === "/snapshots") {
+    (async () => {
+      try {
+        const manifest = await snapshotManager.takeSnapshot({
+          runner: autoCheckpointRunner,
+          getEvents: () => events,
+          broadcast: (ev) => {
+            ev._ts = ev._ts || Date.now();
+            ev._id = crypto.randomUUID();
+            events.push(ev);
+            broadcast(ev);
+            saveEvents();
+          },
+        });
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(manifest));
+      } catch (err) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+    })();
+    return;
+  }
+
+  // GET /snapshots — list bundles
+  if (req.method === "GET" && req.url === "/snapshots") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(snapshotManager.listSnapshots()));
+    return;
+  }
+
+  // GET /snapshots/<id> — get manifest
+  const snapshotMatch = req.url.match(/^\/snapshots\/([^/]+)$/);
+  if (req.method === "GET" && snapshotMatch) {
+    const m = snapshotManager.getSnapshot(snapshotMatch[1]);
+    if (!m) {
+      res.writeHead(404);
+      return res.end("not found");
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    return res.end(JSON.stringify(m));
+  }
+
+  // POST /snapshots/<id>/sessions/<sid>/restore — open a new terminal tab
+  // that restores the given session.
+  const restoreMatch = req.url.match(
+    /^\/snapshots\/([^/]+)\/sessions\/([^/]+)\/restore$/,
+  );
+  if (req.method === "POST" && restoreMatch) {
+    const [, snapId, sid] = restoreMatch;
+    const m = snapshotManager.getSnapshot(snapId);
+    const session = m?.sessions?.find((s) => s.uvs_session_id === sid);
+    if (!session) {
+      res.writeHead(404);
+      return res.end(JSON.stringify({ error: "session not in snapshot" }));
+    }
+    const result = snapshotManager.openTerminalForSession(session);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    return res.end(JSON.stringify(result));
+  }
+
   // GET / — serve dashboard
   if (req.method === "GET" && (req.url === "/" || req.url === "/index.html")) {
     const html = fs.readFileSync(

package/watchtower/snapshot-manager.js

@@ -0,0 +1,305 @@
+// UV Suite Watchtower — snapshot + restore.
+//
+// A "snapshot" bundles the manifest of every active session at a moment in
+// time (sid, cwd, persona, latest checkpoint path) plus a copy of the
+// watchtower's recent event store. It also triggers an immediate Tier B
+// auto-checkpoint for each session so the latest summary is captured.
+//
+// "Restore" doesn't restart Claude Code (we can't — processes are dead).
+// On macOS / Linux it spawns a new terminal tab per session via the OS's
+// AppleScript or terminal-emulator command, passing UVS_RESTORE_FROM=<old-sid>.
+// The next `uvs` launch picks that up and auto-runs `/restore <old-sid>` on
+// turn 1 via the SessionStart hook.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawn } = require("child_process");
+
+const SNAPSHOTS_DIR = path.join(os.homedir(), ".uv-suite", "snapshots");
+const ACTIVE_WINDOW_MS = 60 * 60 * 1000; // sessions with activity in last 1h
+
+function ensureSnapshotsDir() {
+  fs.mkdirSync(SNAPSHOTS_DIR, { recursive: true });
+}
+
+// Group recent events by uvs_session_id, take the most recent metadata for
+// each. Returns one record per active session.
+function activeSessionsFromEvents(events) {
+  const cutoff = Date.now() - ACTIVE_WINDOW_MS;
+  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;
+    // Skip if session was explicitly terminated
+    if (ev.lifecycle === "terminated") {
+      bySession.delete(sid);
+      continue;
+    }
+    const existing = bySession.get(sid) || {
+      uvs_session_id: sid,
+      session_id: ev.session_id || sid,
+      cwd: ev.cwd,
+      name: ev.session_name || "",
+      kind: ev.session_kind || "",
+      purpose: ev.session_purpose || "",
+      priority: ev.session_priority || "",
+      persona: ev.persona || "",
+      first_event_ts: ev._ts,
+      last_event_ts: ev._ts,
+      event_count: 0,
+    };
+    existing.last_event_ts = Math.max(existing.last_event_ts || 0, ev._ts || 0);
+    existing.first_event_ts = Math.min(
+      existing.first_event_ts || Infinity,
+      ev._ts || Infinity,
+    );
+    existing.event_count++;
+    // Refresh metadata fields from latest event (in case /session-init relabeled)
+    if (ev.session_name) existing.name = ev.session_name;
+    if (ev.session_kind) existing.kind = ev.session_kind;
+    if (ev.session_purpose) existing.purpose = ev.session_purpose;
+    if (ev.session_priority) existing.priority = ev.session_priority;
+    if (ev.persona) existing.persona = ev.persona;
+    if (ev.session_id) existing.session_id = ev.session_id;
+    bySession.set(sid, existing);
+  }
+  return [...bySession.values()];
+}
+
+// Find each session's latest checkpoint file (auto-* or final-*)
+function findLatestCheckpoint(cwd, sid) {
+  const dir = path.join(cwd, "uv-out", "checkpoints", sid);
+  if (!fs.existsSync(dir)) return null;
+  try {
+    const files = fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".md") && f !== "latest.md");
+    if (files.length === 0) return null;
+    // Sort by mtime, newest first
+    files.sort((a, b) => {
+      const ma = fs.statSync(path.join(dir, a)).mtimeMs;
+      const mb = fs.statSync(path.join(dir, b)).mtimeMs;
+      return mb - ma;
+    });
+    return path.join(dir, files[0]);
+  } catch {
+    return null;
+  }
+}
+
+// Read first few lines of summary section from a checkpoint file for the
+// snapshot's per-session preview.
+function readCheckpointSummary(cpPath) {
+  if (!cpPath || !fs.existsSync(cpPath)) return "";
+  try {
+    const content = fs.readFileSync(cpPath, "utf-8");
+    // Strip frontmatter
+    const body = content.replace(/^---[\s\S]*?---\s*/m, "");
+    // Look for ## Summary section
+    const m = body.match(/##\s*Summary\s*\n+([\s\S]*?)(?=\n##\s|\n#\s|$)/);
+    if (m) return m[1].trim().slice(0, 600);
+    // Fallback: first 400 chars of body
+    return body.trim().slice(0, 400);
+  } catch {
+    return "";
+  }
+}
+
+async function takeSnapshot({ runner, getEvents, broadcast }) {
+  ensureSnapshotsDir();
+
+  // Trigger an immediate Tier B tick so the snapshot bundles the freshest
+  // possible summaries. We don't block on broadcast; just await the tick.
+  if (runner && runner.tick) {
+    await runner.tick({ getEvents, broadcast });
+  }
+
+  const events = getEvents();
+  const sessions = activeSessionsFromEvents(events);
+
+  const ts = new Date();
+  const id = ts
+    .toISOString()
+    .replace(/[T:]/g, "-")
+    .replace(/\.\d+Z$/, "")
+    .replace(/-(\d\d)$/, "$1");
+  const dir = path.join(SNAPSHOTS_DIR, id);
+  fs.mkdirSync(dir, { recursive: true });
+
+  for (const s of sessions) {
+    s.latest_checkpoint = findLatestCheckpoint(s.cwd, s.uvs_session_id);
+    s.summary_preview = readCheckpointSummary(s.latest_checkpoint);
+  }
+
+  const manifest = {
+    id,
+    created_at: ts.toISOString(),
+    created_at_epoch: Math.floor(ts.getTime() / 1000),
+    sessions,
+    event_count: events.length,
+  };
+
+  fs.writeFileSync(
+    path.join(dir, "manifest.json"),
+    JSON.stringify(manifest, null, 2),
+  );
+  fs.writeFileSync(
+    path.join(dir, "events.json"),
+    JSON.stringify(events, null, 2),
+  );
+
+  // Broadcast a SnapshotTaken event so it shows up in the timeline
+  const event = {
+    event_type: "SnapshotTaken",
+    snapshot_id: id,
+    session_count: sessions.length,
+    _ts: ts.getTime(),
+  };
+  broadcast(event);
+
+  return manifest;
+}
+
+function listSnapshots() {
+  ensureSnapshotsDir();
+  const entries = [];
+  for (const name of fs.readdirSync(SNAPSHOTS_DIR).sort().reverse()) {
+    const manifestPath = path.join(SNAPSHOTS_DIR, name, "manifest.json");
+    try {
+      const m = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+      entries.push({
+        id: m.id,
+        created_at: m.created_at,
+        session_count: m.sessions?.length || 0,
+      });
+    } catch {
+      // skip unreadable bundles
+    }
+  }
+  return entries;
+}
+
+function getSnapshot(id) {
+  const manifestPath = path.join(SNAPSHOTS_DIR, id, "manifest.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+// Spawn a new terminal tab restoring the given session.
+//   macOS:  iTerm2 if TERM_PROGRAM=iTerm.app (or UVS_TERMINAL_APP=iterm),
+//           otherwise Terminal.app. Override either way with UVS_TERMINAL_APP.
+//   Linux:  prefers gnome-terminal then x-terminal-emulator
+//   Other:  returns { ok: false, command: <copy-paste string> }
+function buildRestoreCommand(session) {
+  const persona = session.persona || "professional";
+  const sid = session.uvs_session_id;
+  const cwd = session.cwd;
+  // The new uvs launch reads UVS_RESTORE_FROM and the SessionStart hook
+  // injects "run /restore <sid>" on turn 1.
+  return `cd ${shellEscape(cwd)} && UVS_RESTORE_FROM=${shellEscape(sid)} uvs claude ${shellEscape(persona)}`;
+}
+
+function shellEscape(s) {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+function appleScriptEscape(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+// Pick the macOS terminal app. UVS_TERMINAL_APP wins (values: iterm, terminal),
+// else look at $TERM_PROGRAM, else default to Terminal.app.
+function macTerminalApp() {
+  const explicit = (process.env.UVS_TERMINAL_APP || "").toLowerCase();
+  if (explicit === "iterm" || explicit === "iterm2") return "iterm";
+  if (explicit === "terminal") return "terminal";
+  const tp = process.env.TERM_PROGRAM || "";
+  if (tp === "iTerm.app") return "iterm";
+  return "terminal";
+}
+
+// iTerm2 AppleScript: opens a new tab in the front window if one exists,
+// otherwise a new window. Both code paths end with `write text "..."`.
+function iTermScript(command) {
+  const esc = appleScriptEscape(command);
+  return `
+    tell application "iTerm"
+      activate
+      if (count of windows) = 0 then
+        create window with default profile
+      else
+        tell current window to create tab with default profile
+      end if
+      tell current session of current window to write text "${esc}"
+    end tell
+  `;
+}
+
+function terminalAppScript(command) {
+  return `tell app "Terminal" to do script "${appleScriptEscape(command)}"`;
+}
+
+function openTerminalForSession(session) {
+  const command = buildRestoreCommand(session);
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    const app = macTerminalApp();
+    const script =
+      app === "iterm" ? iTermScript(command) : terminalAppScript(command);
+    const child = spawn("osascript", ["-e", script], {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.unref();
+    return { ok: true, platform, terminal_app: app, command };
+  }
+
+  if (platform === "linux") {
+    // Try gnome-terminal first, fall back to x-terminal-emulator
+    const tryEmulator = (cmd, args) => {
+      try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.unref();
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    if (
+      tryEmulator("gnome-terminal", [
+        "--",
+        "bash",
+        "-c",
+        command + "; exec bash",
+      ]) ||
+      tryEmulator("x-terminal-emulator", [
+        "-e",
+        "bash",
+        "-c",
+        command + "; exec bash",
+      ])
+    ) {
+      return { ok: true, platform, command };
+    }
+  }
+
+  // Windows or unsupported — return the command so the dashboard can offer
+  // a "copy to clipboard" fallback.
+  return { ok: false, platform, command };
+}
+
+module.exports = {
+  takeSnapshot,
+  listSnapshots,
+  getSnapshot,
+  openTerminalForSession,
+  buildRestoreCommand,
+  SNAPSHOTS_DIR,
+};