uv-suite 0.14.0 → 0.17.0

package/bin/cli.js

@@ -29,6 +29,10 @@ function usage() {
     uvs install --persona sport
     uvs info                Show what's installed
 
+  Monitoring:
+    uvs watch               Start Watchtower dashboard (open browser)
+    uvs watch --bg          Start Watchtower in background
+
   Personas:
     spike        Research & docs (Opus, max effort)
     sport        New projects (Sonnet, high effort)
@@ -108,6 +112,42 @@ function launchCodex(persona, extra) {
   child.on('exit', (code) => process.exit(code || 0));
 }
 
+function watch() {
+  const serverScript = path.join(UV_SUITE_DIR, 'watchtower', 'server.js');
+  if (!fs.existsSync(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('');
+
+  if (bg) {
+    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);
+
+    // 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' });
+  } 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' });
+    }, 1000);
+
+    const child = spawn('node', [serverScript], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code || 0));
+  }
+}
+
 // --- Parse and route ---
 
 if (!command || command === '--help' || command === '-h') {
@@ -115,7 +155,9 @@ if (!command || command === '--help' || command === '-h') {
   process.exit(0);
 }
 
-if (command === 'install') {
+if (command === 'watch') {
+  watch();
+} else if (command === 'install') {
   install();
 } else if (command === 'info') {
   info();

package/hooks/session-start.sh

@@ -15,4 +15,8 @@ if [ ! -f "$TODAY_FILE" ]; then
   echo "0" > "$TODAY_FILE"
 fi
 
+# Send to watchtower
+echo '{"session_id":"'$(cat "$STATE_DIR/session-start.txt")'","cwd":"'${CLAUDE_PROJECT_DIR:-.}'"}' | \
+  "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/watchtower-send.sh" "SessionStart" 2>/dev/null
+
 exit 0

package/hooks/watchtower-send.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# UV Suite Hook Helper: Send event to Watchtower server
+# Called by other hooks. Non-blocking. Fails silently if server not running.
+#
+# Usage: echo "$INPUT" | .claude/hooks/watchtower-send.sh "EventType"
+
+EVENT_TYPE="${1:-Unknown}"
+INPUT=$(cat)
+WATCHTOWER_URL="${UVS_WATCHTOWER_URL:-http://localhost:4200}"
+
+# Extract useful fields from the hook input
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}' 2>/dev/null)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+SOURCE_APP=$(basename "$CWD" 2>/dev/null)
+
+# Send to watchtower (non-blocking, fire-and-forget)
+curl -s -X POST "$WATCHTOWER_URL/events" \
+  -H "Content-Type: application/json" \
+  -d "{\"event_type\":\"$EVENT_TYPE\",\"session_id\":\"$SESSION_ID\",\"source_app\":\"$SOURCE_APP\",\"tool_name\":\"$TOOL_NAME\",\"tool_input\":$TOOL_INPUT,\"cwd\":\"$CWD\"}" \
+  &>/dev/null &
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.14.0",
+  "version": "0.17.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",
@@ -37,6 +37,7 @@
     "portable-standards/",
     "settings.json",
     "uv.sh",
+    "watchtower/",
     "install.sh",
     "README.md"
   ]

package/personas/auto.json

@@ -75,7 +75,8 @@
       {
         "matcher": "*",
         "hooks": [
-          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-timer.sh", "timeout": 5 }
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-timer.sh", "timeout": 5 },
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse", "timeout": 2, "async": true }
         ]
       },
       {

package/personas/professional.json

@@ -92,6 +92,12 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-timer.sh",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse",
+            "timeout": 2,
+            "async": true
           }
         ]
       },

package/personas/spike.json

@@ -45,6 +45,12 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse", "timeout": 2, "async": true }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [

package/personas/sport.json

@@ -31,6 +31,12 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/watchtower-send.sh PostToolUse", "timeout": 2, "async": true }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "hooks": [

package/skills/commit/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: commit
+description: >
+  Review, test, slop-check, then commit and optionally open a PR.
+  The ship pipeline: one command from "code complete" to "committed and reviewed."
+argument-hint: "[commit-message or 'pr']"
+user-invocable: true
+allowed-tools:
+  - Read(*)
+  - Grep(*)
+  - Glob(*)
+  - Write(*)
+  - Bash(git *)
+  - Bash(npm test *)
+  - Bash(npm run test *)
+  - Bash(npm run lint *)
+  - Bash(npx jest *)
+  - Bash(npx vitest *)
+  - Bash(pytest *)
+  - Bash(go test *)
+  - Bash(cargo test *)
+  - Bash(gh pr *)
+---
+
+## Intent
+
+$ARGUMENTS
+
+## Current state
+
+!`git status --short 2>/dev/null | head -30 || echo "not a git repo"`
+
+!`git diff --cached --stat 2>/dev/null || echo "nothing staged"`
+
+!`git diff --stat 2>/dev/null || echo "no unstaged changes"`
+
+## Pipeline — run these steps in order
+
+### 1. Run tests
+
+Find and run the project's test command. If tests fail, fix the failures before continuing. If they can't be fixed in 2 attempts, stop and report.
+
+### 2. Run lint
+
+If a lint command exists (npm run lint, ruff check, etc.), run it. Fix auto-fixable issues.
+
+### 3. Quick slop check
+
+Scan changed files for the most obvious patterns:
+- `toBeTruthy()` / `toBeDefined()` in test files
+- Bare `except: pass` in Python
+
+Don't run the full /slop-check agent — just grep for mechanical patterns.
+
+### 4. Review the diff
+
+Read the full diff. Check for:
+- Correctness: does it do what it should?
+- Security: any obvious issues? (hardcoded secrets, missing auth checks)
+- Completeness: anything half-done or TODO'd?
+
+If you find issues, fix them. If they need human input, stop and ask.
+
+### 5. Stage and commit
+
+- Stage the relevant files (not `.env`, not `node_modules`, not build artifacts)
+- Write a commit message. If the user provided one in $ARGUMENTS, use it. Otherwise, write a concise message that describes the WHY, not the WHAT.
+- Commit.
+
+### 6. Open PR (if requested)
+
+If the user said "pr" in their arguments, or if on a feature branch:
+- Push the branch
+- Open a PR with `gh pr create`
+- Title: short, under 70 chars
+- Body: summary bullets + test plan
+
+### 7. Checkpoint
+
+After committing, write a checkpoint to `uv-out/checkpoints/latest.md` with what was committed.
+
+## Danger zones
+
+!`cat DANGER-ZONES.md 2>/dev/null || echo "No DANGER-ZONES.md"`
+
+## Rules
+
+- If tests fail and can't be fixed quickly, STOP. Don't commit broken code.
+- If the diff touches a danger zone file, flag it before committing.
+- Prefer separate commits per logical change if there are unrelated changes staged.
+- Never commit .env, credentials, or secrets.

package/skills/investigate/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: investigate
+description: >
+  Systematic root-cause debugging. Traces data flow, tests hypotheses,
+  narrows scope. Stops after 3 failed attempts and escalates.
+  Use when something is broken and you don't know why.
+argument-hint: "[bug-description or error-message]"
+user-invocable: true
+context: fork
+agent: reviewer
+model: claude-opus-4-6
+effort: max
+allowed-tools:
+  - Read(*)
+  - Grep(*)
+  - Glob(*)
+  - Bash(git log *)
+  - Bash(git diff *)
+  - Bash(git blame *)
+  - Bash(git show *)
+  - Bash(npm test *)
+  - Bash(npm run *)
+  - Bash(npx *)
+  - Bash(pytest *)
+  - Bash(go test *)
+  - Bash(cargo test *)
+  - Bash(curl *)
+  - Bash(node *)
+  - Bash(python *)
+---
+
+## The bug
+
+$ARGUMENTS
+
+## Project context
+
+!`cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md"`
+
+## Codebase map
+
+!`cat uv-out/map-codebase.md 2>/dev/null | head -60 || echo "No codebase map"`
+
+## Recent changes (potential cause)
+
+!`git log --oneline -15 2>/dev/null || echo "no git"`
+
+## Latest checkpoint
+
+!`cat uv-out/checkpoints/latest.md 2>/dev/null | head -30 || echo "No checkpoint"`
+
+## Investigation methodology
+
+Follow this process strictly:
+
+### Phase 1: Reproduce
+
+Before investigating, reproduce the bug. Run the failing test, hit the failing endpoint, trigger the error. If you can't reproduce it, say so and ask for reproduction steps.
+
+### Phase 2: Narrow scope
+
+Form a hypothesis about WHERE the bug is:
+1. Read the error message/stack trace carefully
+2. Identify the failing component (which file, which function, which layer)
+3. Check recent changes to that component (`git log --oneline [file]`)
+4. Check if the component was modified in the last 5 commits (`git diff HEAD~5 [file]`)
+
+State your hypothesis explicitly: "I think the bug is in [X] because [Y]."
+
+### Phase 3: Test the hypothesis
+
+Verify your hypothesis with the smallest possible test:
+- Add a log/print statement
+- Write a focused test case
+- Run a specific command that isolates the behavior
+
+If the hypothesis is wrong, form a new one. Track what you've ruled out.
+
+### Phase 4: Fix or escalate
+
+If you found the root cause within 3 attempts: fix it, run the tests, verify.
+
+If you haven't found it after 3 attempts:
+
+```
+## Stuck: [bug description]
+
+Ruled out:
+1. [Hypothesis 1] — wrong because [evidence]
+2. [Hypothesis 2] — wrong because [evidence]  
+3. [Hypothesis 3] — wrong because [evidence]
+
+Remaining possibilities:
+- [What I haven't checked yet]
+
+What I need:
+- [Specific question or access needed from the human]
+```
+
+## Rules
+
+- NO FIXES WITHOUT INVESTIGATION. Don't guess and patch. Find the root cause first.
+- State hypotheses explicitly before testing them.
+- Track what you've ruled out so you don't revisit.
+- 3 attempts max. Then escalate with structured findings.
+- If the bug is in code you don't understand, run /map-codebase on that area first.
+
+## Artifact output
+
+Write investigation findings to `uv-out/investigate-YYYY-MM-DD.md`. Include: bug description, hypotheses tested, root cause found (or not), fix applied (or escalation).

package/skills/uv-help/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: uv-help
+description: >
+  Show all UV Suite skills, agents, hooks, guardrails, and personas.
+  Use when you want to know what's available or how to use a specific feature.
+argument-hint: "[skill-name or topic]"
+user-invocable: true
+allowed-tools:
+  - Read(*)
+  - Glob(*)
+---
+
+## UV Suite Help
+
+$ARGUMENTS
+
+If the user asked about a specific skill or topic, focus on that. Otherwise, show the full overview below.
+
+## Active persona
+
+!`grep "Active persona" CLAUDE.md 2>/dev/null || echo "Unknown — check .claude/settings.json"`
+
+## All available skills
+
+Every skill accepts free-form arguments to direct the agent. Examples shown below.
+
+### Understand
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/map-codebase [focus]` | Build a knowledge graph of the codebase | `/map-codebase focus on the auth flow and session management` |
+| `/map-stack [dir]` | Map multiple services and their connections | `/map-stack show how layer3-max calls layer2-pie` |
+
+### Plan
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/spec [requirements]` | Write a technical specification | `/spec webhook retry with exponential backoff, max 3 retries` |
+| `/architect [spec]` | Design architecture, decompose into Acts | `/architect design for horizontal scaling, expect 10x traffic` |
+
+### Build
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/write-tests [target]` | Generate tests matching project conventions | `/write-tests src/auth/login.ts focus on error paths` |
+| `/write-evals [prompt]` | Write AI/LLM evaluation cases | `/write-evals test the search ranking prompt for adversarial inputs` |
+| `/prototype [concept]` | Build a static React prototype | `/prototype event booking app with calendar and payment flow` |
+
+### Review
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/review [focus]` | Code review: correctness, security, perf, slop | `/review pay attention to the new database migration` |
+| `/slop-check [target]` | Detect 6 categories of AI-generated slop | `/slop-check src/components/ check for over-engineering` |
+| `/security-review [target]` | OWASP audit, dependency scan, secret detection | `/security-review src/payments/ focus on webhook signature validation` |
+
+### Ship
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/commit [message]` | Test, lint, review, commit (optionally open PR) | `/commit "Add webhook retry logic" pr` |
+| `/investigate [bug]` | Root-cause debugging (3 attempts then escalate) | `/investigate search returns stale results after reindex` |
+
+### Session
+
+| Skill | What it does | Example |
+|-------|-------------|---------|
+| `/checkpoint [label]` | Save session state for next time | `/checkpoint auth-refactor` |
+| `/restore` | Load latest checkpoint at session start | `/restore` |
+
+## Agents (spawned by skills)
+
+| Agent | Model | Used by |
+|-------|-------|---------|
+| Cartographer | Opus | /map-codebase, /map-stack |
+| Spec Writer | Opus | /spec |
+| Architect | Opus | /architect |
+| Reviewer | Opus | /review, /investigate |
+| Test Writer | Sonnet | /write-tests |
+| Eval Writer | Opus | /write-evals |
+| Anti-Slop Guard | Opus | /slop-check |
+| Prototype Builder | Sonnet | /prototype |
+| DevOps | Opus | (direct invocation) |
+| Security | Opus | /security-review |
+
+## Hooks (automatic, you don't invoke these)
+
+!`ls .claude/hooks/*.sh 2>/dev/null | while read f; do echo "- $(basename $f)"; done || echo "No hooks installed"`
+
+## Guardrails (anti-slop rules, active as context)
+
+!`ls .claude/rules/*.md 2>/dev/null | while read f; do echo "- $(basename $f .md)"; done || echo "No guardrails installed"`
+
+## Personas
+
+| Persona | Launch | For |
+|---------|--------|-----|
+| Spike | `uvs spike` | Research, docs, architecture analysis |
+| Sport | `uvs sport` | New projects, fast prototyping |
+| Professional | `uvs pro` | Production code, full review rigor |
+| Auto | `uvs auto` | Autonomous execution, clear specs |
+
+## Artifacts
+
+All agent output goes to `uv-out/`. Agents read each other's prior output automatically.
+
+!`ls uv-out/*.md uv-out/**/*.md 2>/dev/null | head -15 || echo "No artifacts yet — run a skill to generate some"`
+
+## Tips
+
+- **Direct the agent:** Every skill accepts arguments. "/review" does a generic review. "/review focus on the error handling in the retry logic" gives targeted results.
+- **Run in parallel:** "Run /review, /slop-check, and /security-review in parallel" — Claude spawns all three simultaneously.
+- **Checkpoint before stopping:** "/checkpoint" saves your session state. "/restore" loads it next time.
+- **Use the right persona:** `uvs spike` for research, `uvs pro` for production code, `uvs auto` to let it run.

package/watchtower/dashboard.html

@@ -0,0 +1,257 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>UV Suite Watchtower</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', system-ui, sans-serif; background: #000; color: #f5f5f7; }
+  .header { padding: 16px 24px; border-bottom: 1px solid #2d2d2f; display: flex; align-items: center; justify-content: space-between; }
+  .header h1 { font-size: 16px; font-weight: 600; letter-spacing: -0.01em; }
+  .header .status { font-size: 11px; color: #86868b; }
+  .header .status .dot { display: inline-block; width: 6px; height: 6px; border-radius: 50%; margin-right: 4px; }
+  .header .status .dot.on { background: #30d158; }
+  .header .status .dot.off { background: #ff453a; }
+
+  .filters { padding: 8px 24px; border-bottom: 1px solid #1d1d1f; display: flex; gap: 8px; flex-wrap: wrap; }
+  .filters select, .filters button { background: #1d1d1f; color: #a1a1a6; border: 1px solid #2d2d2f; border-radius: 6px; padding: 4px 10px; font-size: 11px; cursor: pointer; }
+  .filters select:focus, .filters button:hover { border-color: #424245; color: #f5f5f7; }
+  .filters button.active { background: #0071e3; color: #fff; border-color: #0071e3; }
+
+  .stats { padding: 12px 24px; display: flex; gap: 24px; border-bottom: 1px solid #1d1d1f; }
+  .stat { text-align: center; }
+  .stat .n { font-size: 20px; font-weight: 600; }
+  .stat .l { font-size: 10px; color: #86868b; text-transform: uppercase; letter-spacing: 0.5px; margin-top: 2px; }
+
+  .sessions { padding: 12px 24px; border-bottom: 1px solid #1d1d1f; display: flex; gap: 8px; flex-wrap: wrap; }
+  .session-tag { padding: 3px 10px; border-radius: 12px; font-size: 11px; font-weight: 500; cursor: pointer; border: 1px solid transparent; }
+  .session-tag:hover { border-color: #424245; }
+  .session-tag.active { border-color: #fff; }
+
+  .timeline { padding: 8px 0; overflow-y: auto; max-height: calc(100vh - 220px); }
+  .event { padding: 6px 24px; display: grid; grid-template-columns: 70px 100px 120px 1fr 80px; gap: 8px; align-items: center; font-size: 12px; border-bottom: 1px solid #0d0d0d; }
+  .event:hover { background: #0d0d0d; }
+  .event .time { color: #6e6e73; font-variant-numeric: tabular-nums; font-family: 'SF Mono', monospace; font-size: 11px; }
+  .event .type { font-weight: 500; }
+  .event .session { font-size: 11px; border-radius: 8px; padding: 1px 8px; display: inline-block; }
+  .event .detail { color: #a1a1a6; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .event .duration { color: #6e6e73; font-family: 'SF Mono', monospace; font-size: 11px; text-align: right; }
+
+  .empty { padding: 60px 24px; text-align: center; color: #6e6e73; }
+  .empty p { margin-top: 8px; font-size: 13px; }
+
+  /* Event type colors */
+  .type-SessionStart { color: #30d158; }
+  .type-SessionEnd, .type-Stop { color: #ff453a; }
+  .type-PreToolUse { color: #0a84ff; }
+  .type-PostToolUse { color: #64d2ff; }
+  .type-PostToolUseFailure { color: #ff6961; }
+  .type-UserPromptSubmit { color: #ffd60a; }
+  .type-SubagentStart { color: #bf5af2; }
+  .type-SubagentStop { color: #ac8ee0; }
+  .type-Notification { color: #ff9f0a; }
+  .type-PermissionRequest { color: #ff375f; }
+  .type-PreCompact { color: #6e6e73; }
+</style>
+</head>
+<body>
+
+<div class="header">
+  <h1>UV Suite Watchtower</h1>
+  <div class="status"><span class="dot" id="statusDot"></span><span id="statusText">Connecting...</span></div>
+</div>
+
+<div class="stats">
+  <div class="stat"><div class="n" id="sessionCount">0</div><div class="l">Sessions</div></div>
+  <div class="stat"><div class="n" id="eventCount">0</div><div class="l">Events</div></div>
+  <div class="stat"><div class="n" id="toolCount">0</div><div class="l">Tool calls</div></div>
+  <div class="stat"><div class="n" id="errorCount">0</div><div class="l">Errors</div></div>
+</div>
+
+<div class="sessions" id="sessionBar"></div>
+
+<div class="filters">
+  <select id="filterType"><option value="">All events</option></select>
+  <select id="filterSession"><option value="">All sessions</option></select>
+  <button id="btnClear" onclick="clearEvents()">Clear</button>
+  <button id="btnAutoScroll" class="active" onclick="toggleAutoScroll()">Auto-scroll</button>
+</div>
+
+<div class="timeline" id="timeline">
+  <div class="empty" id="emptyState">
+    <p><strong>Waiting for events</strong></p>
+    <p>Start a Claude Code session with UV Suite hooks.<br>Events will appear here in real-time.</p>
+  </div>
+</div>
+
+<script>
+const timeline = document.getElementById('timeline');
+const emptyState = document.getElementById('emptyState');
+const filterType = document.getElementById('filterType');
+const filterSession = document.getElementById('filterSession');
+const statusDot = document.getElementById('statusDot');
+const statusText = document.getElementById('statusText');
+const sessionBar = document.getElementById('sessionBar');
+
+let events = [];
+let sessions = {};
+let autoScroll = true;
+let selectedSession = '';
+let selectedType = '';
+let ws;
+
+// Session colors
+const palette = ['#0a84ff','#30d158','#ff9f0a','#bf5af2','#ff375f','#64d2ff','#ffd60a','#ac8ee0','#ff6961','#5e5ce6'];
+let colorIdx = 0;
+function sessionColor(id) {
+  if (!sessions[id]) {
+    sessions[id] = { color: palette[colorIdx++ % palette.length], count: 0, lastEvent: null };
+    updateSessionBar();
+    updateFilterSession();
+  }
+  sessions[id].count++;
+  sessions[id].lastEvent = Date.now();
+  return sessions[id].color;
+}
+
+function formatTime(ts) {
+  const d = new Date(ts);
+  return d.toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
+}
+
+function shortSession(id) {
+  if (!id) return '—';
+  return id.length > 12 ? id.slice(0, 8) + '...' : id;
+}
+
+function eventDetail(ev) {
+  if (ev.tool_name) return ev.tool_name + (ev.tool_input?.command ? ': ' + ev.tool_input.command.slice(0, 60) : '');
+  if (ev.tool_input?.file_path) return ev.tool_input.file_path;
+  if (ev.source_app) return ev.source_app;
+  if (ev.message) return ev.message;
+  return '';
+}
+
+function renderEvent(ev) {
+  const sid = ev.session_id || ev.source_app || 'unknown';
+  const color = sessionColor(sid);
+  const div = document.createElement('div');
+  div.className = 'event';
+  div.innerHTML = `
+    <span class="time">${formatTime(ev._ts)}</span>
+    <span class="type type-${ev.event_type || ev.hook_event_name || ''}">${ev.event_type || ev.hook_event_name || '?'}</span>
+    <span class="session" style="background:${color}22;color:${color}">${shortSession(sid)}</span>
+    <span class="detail" title="${eventDetail(ev)}">${eventDetail(ev)}</span>
+    <span class="duration">${ev.duration_ms ? ev.duration_ms + 'ms' : ''}</span>
+  `;
+
+  // Check filters
+  const typeMatch = !selectedType || (ev.event_type || ev.hook_event_name) === selectedType;
+  const sessMatch = !selectedSession || sid === selectedSession;
+  if (!typeMatch || !sessMatch) div.style.display = 'none';
+
+  return div;
+}
+
+function addEvent(ev) {
+  events.push(ev);
+  if (emptyState.parentNode) emptyState.remove();
+  timeline.appendChild(renderEvent(ev));
+  updateStats();
+  updateFilterType(ev);
+  if (autoScroll) timeline.scrollTop = timeline.scrollHeight;
+}
+
+function updateStats() {
+  document.getElementById('sessionCount').textContent = Object.keys(sessions).length;
+  document.getElementById('eventCount').textContent = events.length;
+  document.getElementById('toolCount').textContent = events.filter(e => (e.event_type || e.hook_event_name || '').includes('ToolUse')).length;
+  document.getElementById('errorCount').textContent = events.filter(e => (e.event_type || e.hook_event_name || '').includes('Failure')).length;
+}
+
+function updateSessionBar() {
+  sessionBar.innerHTML = '';
+  for (const [id, s] of Object.entries(sessions)) {
+    const tag = document.createElement('span');
+    tag.className = 'session-tag' + (selectedSession === id ? ' active' : '');
+    tag.style.background = s.color + '22';
+    tag.style.color = s.color;
+    tag.textContent = shortSession(id) + ' (' + s.count + ')';
+    tag.onclick = () => { selectedSession = selectedSession === id ? '' : id; refilter(); updateSessionBar(); };
+    sessionBar.appendChild(tag);
+  }
+}
+
+const knownTypes = new Set();
+function updateFilterType(ev) {
+  const t = ev.event_type || ev.hook_event_name;
+  if (t && !knownTypes.has(t)) {
+    knownTypes.add(t);
+    const opt = document.createElement('option');
+    opt.value = t; opt.textContent = t;
+    filterType.appendChild(opt);
+  }
+}
+
+function updateFilterSession() {
+  filterSession.innerHTML = '<option value="">All sessions</option>';
+  for (const id of Object.keys(sessions)) {
+    const opt = document.createElement('option');
+    opt.value = id; opt.textContent = shortSession(id);
+    filterSession.appendChild(opt);
+  }
+}
+
+function refilter() {
+  selectedType = filterType.value;
+  selectedSession = filterSession.value;
+  const rows = timeline.querySelectorAll('.event');
+  rows.forEach((row, i) => {
+    const ev = events[i];
+    const sid = ev.session_id || ev.source_app || 'unknown';
+    const type = ev.event_type || ev.hook_event_name || '';
+    const show = (!selectedType || type === selectedType) && (!selectedSession || sid === selectedSession);
+    row.style.display = show ? '' : 'none';
+  });
+}
+
+filterType.onchange = refilter;
+filterSession.onchange = refilter;
+
+function clearEvents() { events = []; sessions = {}; colorIdx = 0; timeline.innerHTML = ''; updateStats(); sessionBar.innerHTML = ''; }
+function toggleAutoScroll() {
+  autoScroll = !autoScroll;
+  document.getElementById('btnAutoScroll').classList.toggle('active', autoScroll);
+}
+
+// WebSocket connection
+function connect() {
+  const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  ws = new WebSocket(`${proto}//${location.host}/ws`);
+
+  ws.onopen = () => {
+    statusDot.className = 'dot on';
+    statusText.textContent = 'Connected';
+  };
+
+  ws.onclose = () => {
+    statusDot.className = 'dot off';
+    statusText.textContent = 'Disconnected — reconnecting...';
+    setTimeout(connect, 2000);
+  };
+
+  ws.onmessage = (msg) => {
+    const data = JSON.parse(msg.data);
+    if (data.type === 'init' && data.events) {
+      data.events.forEach(addEvent);
+    } else {
+      addEvent(data);
+    }
+  };
+}
+
+connect();
+</script>
+</body>
+</html>

package/watchtower/events.json

@@ -0,0 +1,11 @@
+[
+  {
+    "event_type": "PostToolUse",
+    "session_id": "test-123",
+    "source_app": "uv-suite",
+    "tool_name": "Edit",
+    "cwd": "/tmp",
+    "_ts": 1776756371726,
+    "_id": "3f130976-6226-47ea-a477-18a16e194415"
+  }
+]

package/watchtower/server.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+// UV Suite Watchtower — lightweight observability server
+// Zero dependencies beyond Node.js (uses built-in http, fs, ws via raw upgrade)
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const PORT = process.env.UVS_WATCHTOWER_PORT || 4200;
+const DATA_FILE = path.join(__dirname, 'events.json');
+const MAX_EVENTS = 500;
+
+// In-memory event store
+let events = [];
+try {
+  if (fs.existsSync(DATA_FILE)) {
+    events = JSON.parse(fs.readFileSync(DATA_FILE, 'utf-8'));
+  }
+} catch (e) {
+  events = [];
+}
+
+// WebSocket clients
+const clients = new Set();
+
+function broadcast(event) {
+  const msg = JSON.stringify(event);
+  for (const ws of clients) {
+    try { ws.send(msg); } catch (e) { clients.delete(ws); }
+  }
+}
+
+function saveEvents() {
+  // Keep only the last MAX_EVENTS
+  if (events.length > MAX_EVENTS) {
+    events = events.slice(-MAX_EVENTS);
+  }
+  fs.writeFileSync(DATA_FILE, JSON.stringify(events, null, 2));
+}
+
+// Minimal WebSocket handshake (no dependency needed)
+const crypto = require('crypto');
+
+function upgradeToWebSocket(req, socket) {
+  const key = req.headers['sec-websocket-key'];
+  const accept = crypto.createHash('sha1')
+    .update(key + '258EAFA5-E914-47DA-95CA-5AB5DC085B11')
+    .digest('base64');
+
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    `Sec-WebSocket-Accept: ${accept}\r\n` +
+    '\r\n'
+  );
+
+  const ws = {
+    send(data) {
+      const buf = Buffer.from(data);
+      const frame = [];
+      frame.push(0x81); // text frame
+      if (buf.length < 126) {
+        frame.push(buf.length);
+      } else if (buf.length < 65536) {
+        frame.push(126, (buf.length >> 8) & 0xff, buf.length & 0xff);
+      } else {
+        frame.push(127);
+        for (let i = 7; i >= 0; i--) frame.push((buf.length >> (i * 8)) & 0xff);
+      }
+      socket.write(Buffer.concat([Buffer.from(frame), buf]));
+    }
+  };
+
+  clients.add(ws);
+  socket.on('close', () => clients.delete(ws));
+  socket.on('error', () => clients.delete(ws));
+
+  // Send recent events on connect
+  ws.send(JSON.stringify({ type: 'init', events: events.slice(-100) }));
+}
+
+const server = http.createServer((req, res) => {
+  // CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(200);
+    return res.end();
+  }
+
+  // POST /events — receive hook events
+  if (req.method === 'POST' && req.url === '/events') {
+    let body = '';
+    req.on('data', chunk => body += chunk);
+    req.on('end', () => {
+      try {
+        const event = JSON.parse(body);
+        event._ts = Date.now();
+        event._id = crypto.randomUUID();
+        events.push(event);
+        broadcast(event);
+        saveEvents();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end('{"ok":true}');
+      } catch (e) {
+        res.writeHead(400);
+        res.end('{"error":"invalid json"}');
+      }
+    });
+    return;
+  }
+
+  // GET /events — fetch recent events
+  if (req.method === 'GET' && req.url.startsWith('/events')) {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(events.slice(-100)));
+    return;
+  }
+
+  // GET / — serve dashboard
+  if (req.method === 'GET' && (req.url === '/' || req.url === '/index.html')) {
+    const html = fs.readFileSync(path.join(__dirname, 'dashboard.html'), 'utf-8');
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('not found');
+});
+
+server.on('upgrade', (req, socket, head) => {
+  if (req.url === '/ws') {
+    upgradeToWebSocket(req, socket);
+  } else {
+    socket.destroy();
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`UV Suite Watchtower running at http://localhost:${PORT}`);
+  console.log(`${events.length} events loaded from disk`);
+  console.log(`Waiting for hook events on POST http://localhost:${PORT}/events`);
+});