panopticon-cli 0.4.7 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panopticon-cli",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Multi-agent orchestration for AI coding assistants (Claude Code, Codex, Cursor, Gemini CLI)",
   "keywords": [
     "ai-agents",
@@ -39,7 +39,7 @@
     "dist",
     "templates",
     "skills",
-    "scripts/git-hooks",
+    "scripts",
     "README.md",
     "LICENSE"
   ],

package/scripts/heartbeat-hook

@@ -0,0 +1,149 @@
+#!/bin/bash
+# ~/.panopticon/bin/heartbeat-hook
+# Called by Claude Code after every tool use with JSON on stdin
+#
+# This hook receives PostToolUse event data from Claude Code and writes
+# rich heartbeat information to enable real-time agent monitoring.
+
+# Don't use set -e - we want the hook to be resilient to failures
+# and never break Claude Code execution
+
+# Parse tool info from stdin
+TOOL_INFO=$(cat 2>/dev/null || echo '{}')
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+  echo "Warning: jq not found. Heartbeat hook requires jq to parse tool data." >&2
+  exit 0  # Silent failure - don't break Claude Code execution
+fi
+
+# Extract tool name and input (truncate input to 100 chars to avoid huge files)
+TOOL_NAME=$(echo "$TOOL_INFO" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")
+TOOL_INPUT=$(echo "$TOOL_INFO" | jq -r '.tool_input | tostring | .[0:100] // ""' 2>/dev/null || echo "")
+
+# Get agent ID from env (set by pan work issue) or tmux session name
+# Only use tmux session name if we're actually INSIDE a tmux session ($TMUX is set)
+if [ -n "$PANOPTICON_AGENT_ID" ]; then
+  AGENT_ID="$PANOPTICON_AGENT_ID"
+elif [ -n "$TMUX" ]; then
+  AGENT_ID=$(tmux display-message -p '#S' 2>/dev/null)
+else
+  AGENT_ID="main-cli"
+fi
+AGENT_ID="${AGENT_ID:-unknown}"
+
+# Get current beads task from cache (if exists)
+TASK_CACHE="$HOME/.panopticon/agents/$AGENT_ID/current-task.json"
+CURRENT_TASK=""
+if [ -f "$TASK_CACHE" ]; then
+  CURRENT_TASK=$(jq -r '.title // ""' "$TASK_CACHE" 2>/dev/null || echo "")
+fi
+
+# Get git branch (fast, single command) - suppress all errors
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || true)
+GIT_BRANCH="${GIT_BRANCH:-unknown}"
+
+# Get workspace from pwd
+WORKSPACE=$(pwd)
+
+# Ensure heartbeat directory exists
+HEARTBEAT_DIR="$HOME/.panopticon/heartbeats"
+mkdir -p "$HEARTBEAT_DIR"
+
+# Ensure agent state directory exists for activity log
+AGENT_DIR="$HOME/.panopticon/agents/$AGENT_ID"
+mkdir -p "$AGENT_DIR"
+
+# Write heartbeat atomically (write to temp file, then move)
+# Use jq to properly escape all strings in the JSON output
+TEMP_FILE="$HEARTBEAT_DIR/$AGENT_ID.json.tmp"
+jq -n \
+  --arg timestamp "$(date -Iseconds)" \
+  --arg agent_id "$AGENT_ID" \
+  --arg tool_name "$TOOL_NAME" \
+  --arg last_action "$TOOL_INPUT" \
+  --arg current_task "$CURRENT_TASK" \
+  --arg git_branch "$GIT_BRANCH" \
+  --arg workspace "$WORKSPACE" \
+  --argjson pid $$ \
+  '{
+    timestamp: $timestamp,
+    agent_id: $agent_id,
+    tool_name: $tool_name,
+    last_action: $last_action,
+    current_task: $current_task,
+    git_branch: $git_branch,
+    workspace: $workspace,
+    pid: $pid
+  }' > "$TEMP_FILE" 2>/dev/null || true
+
+# Atomic move to avoid race conditions
+mv "$TEMP_FILE" "$HEARTBEAT_DIR/$AGENT_ID.json" 2>/dev/null || true
+
+# Append to activity log (JSONL format)
+ACTIVITY_FILE="$AGENT_DIR/activity.jsonl"
+
+# Create activity entry
+ACTIVITY_ENTRY=$(jq -n \
+  --arg ts "$(date -Iseconds)" \
+  --arg tool "$TOOL_NAME" \
+  --arg action "$TOOL_INPUT" \
+  '{
+    ts: $ts,
+    tool: $tool,
+    action: $action
+  }' 2>/dev/null || echo "")
+
+# Append to activity log if we successfully created the entry
+if [ -n "$ACTIVITY_ENTRY" ]; then
+  echo "$ACTIVITY_ENTRY" >> "$ACTIVITY_FILE" 2>/dev/null || true
+
+  # Prune to last 100 entries (use tail for atomic operation)
+  if [ -f "$ACTIVITY_FILE" ]; then
+    TEMP_ACTIVITY="$ACTIVITY_FILE.tmp"
+    tail -n 100 "$ACTIVITY_FILE" > "$TEMP_ACTIVITY" 2>/dev/null && mv "$TEMP_ACTIVITY" "$ACTIVITY_FILE" 2>/dev/null || true
+  fi
+fi
+
+# Update agent runtime state with latest activity timestamp (PAN-119)
+STATE_FILE="$AGENT_DIR/state.json"
+TIMESTAMP="$(date -Iseconds)"
+
+if [ -f "$STATE_FILE" ]; then
+  # Update existing state file's lastActivity field
+  TEMP_STATE="$STATE_FILE.tmp"
+  jq --arg ts "$TIMESTAMP" --arg tool "$TOOL_NAME" \
+    '.lastActivity = $ts | .currentTool = $tool | .state = "active"' \
+    "$STATE_FILE" > "$TEMP_STATE" 2>/dev/null && mv "$TEMP_STATE" "$STATE_FILE" 2>/dev/null || true
+else
+  # Create initial state file
+  jq -n \
+    --arg ts "$TIMESTAMP" \
+    --arg tool "$TOOL_NAME" \
+    '{
+      state: "active",
+      lastActivity: $ts,
+      currentTool: $tool
+    }' > "$STATE_FILE" 2>/dev/null || true
+fi
+
+# Record cost event from tool usage (PAN-81)
+# Find the record-cost-event.js script - check multiple locations
+COST_SCRIPT=""
+if [ -f "$HOME/.panopticon/bin/record-cost-event.js" ]; then
+  COST_SCRIPT="$HOME/.panopticon/bin/record-cost-event.js"
+elif [ -f "$(dirname "$0")/record-cost-event.js" ]; then
+  COST_SCRIPT="$(dirname "$0")/record-cost-event.js"
+fi
+
+if [ -n "$COST_SCRIPT" ] && [ -f "$COST_SCRIPT" ]; then
+  # Export issue context for the cost recording script
+  export PANOPTICON_ISSUE_ID="${PANOPTICON_ISSUE_ID:-UNKNOWN}"
+  export PANOPTICON_SESSION_TYPE="${PANOPTICON_SESSION_TYPE:-implementation}"
+
+  # Call cost recording script with tool info on stdin
+  echo "$TOOL_INFO" | node "$COST_SCRIPT" 2>/dev/null || true
+fi
+
+# Always exit successfully - never break Claude Code execution
+exit 0

package/scripts/install-git-hooks.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+#
+# Install Panopticon git hooks in a project's repos
+# Usage: ./install-git-hooks.sh /path/to/project
+#
+# For poly-repos, this will find all .git directories and install hooks in each.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOKS_DIR="$SCRIPT_DIR/git-hooks"
+TARGET_DIR="${1:-.}"
+
+if [ ! -d "$TARGET_DIR" ]; then
+    echo "Error: Directory does not exist: $TARGET_DIR"
+    exit 1
+fi
+
+echo "Installing Panopticon git hooks in: $TARGET_DIR"
+echo ""
+
+# Find all .git directories (not files - those are worktrees)
+# Also exclude node_modules, target, etc.
+find "$TARGET_DIR" -maxdepth 4 -type d -name ".git" \
+    -not -path "*/node_modules/*" \
+    -not -path "*/target/*" \
+    -not -path "*/.git/*" \
+    -not -path "*/workspaces/*" \
+    2>/dev/null | while read git_dir; do
+
+    hooks_target="$git_dir/hooks"
+    repo_dir="$(dirname "$git_dir")"
+
+    echo "Installing hooks in: $repo_dir"
+
+    # Create hooks directory if it doesn't exist
+    mkdir -p "$hooks_target"
+
+    # Install each hook
+    for hook in "$HOOKS_DIR"/*; do
+        if [ -f "$hook" ]; then
+            hook_name=$(basename "$hook")
+            target_hook="$hooks_target/$hook_name"
+
+            # Check if hook already exists
+            if [ -f "$target_hook" ] && [ ! -L "$target_hook" ]; then
+                echo "  ⚠️  $hook_name: existing hook found, creating backup"
+                mv "$target_hook" "$target_hook.backup"
+            fi
+
+            # Create symlink to our hook
+            ln -sf "$hook" "$target_hook"
+            echo "  ✓ $hook_name installed"
+        fi
+    done
+
+    echo ""
+done
+
+echo "Done! Git hooks installed."
+echo ""
+echo "The post-checkout hook will warn if the main project directory"
+echo "is checked out to a branch other than 'main'."
+echo ""
+echo "To enable auto-revert (automatically switch back to main):"
+echo "  export PANOPTICON_AUTO_REVERT_CHECKOUT=1"

package/scripts/notify-complete

@@ -0,0 +1,79 @@
+#!/bin/bash
+# notify-complete: Send desktop notification when agent completes work
+# Part of Panopticon - works on WSL2/Windows, Linux, and macOS
+#
+# Usage: notify-complete <issue-id> <title> [mr-url]
+#
+# Examples:
+#   notify-complete MIN-665 "Fixed login button"
+#   notify-complete PAN-96 "Implemented templates" "https://gitlab.com/mr/123"
+
+ISSUE_ID="${1:-UNKNOWN}"
+TITLE="${2:-Agent completed work}"
+MR_URL="${3:-}"
+
+# Log to completion file
+COMPLETION_LOG="$HOME/.panopticon/agent-completed.log"
+mkdir -p "$(dirname "$COMPLETION_LOG")"
+echo "$(date '+%Y-%m-%d %H:%M:%S') | ${ISSUE_ID} | ${TITLE} | ${MR_URL}" >> "$COMPLETION_LOG"
+
+# Detect platform and send notification
+send_notification() {
+  local title="$1"
+  local message="$2"
+
+  # WSL2/Windows - use PowerShell toast notifications
+  if command -v powershell.exe &>/dev/null; then
+    powershell.exe -Command "
+\$xml = @\"
+<toast>
+  <visual>
+    <binding template=\"ToastText02\">
+      <text id=\"1\">${title}</text>
+      <text id=\"2\">${message}</text>
+    </binding>
+  </visual>
+  <audio src=\"ms-winsoundevent:Notification.Default\"/>
+</toast>
+\"@
+
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+
+\$template = New-Object Windows.Data.Xml.Dom.XmlDocument
+\$template.LoadXml(\$xml)
+\$toast = New-Object Windows.UI.Notifications.ToastNotification \$template
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Panopticon').Show(\$toast)
+" 2>/dev/null && return 0
+
+    # Fallback: MessageBox
+    powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('${message}', '${title}', 'OK', 'Information')" 2>/dev/null &
+    return 0
+  fi
+
+  # macOS - use osascript
+  if command -v osascript &>/dev/null; then
+    osascript -e "display notification \"${message}\" with title \"${title}\"" 2>/dev/null
+    return 0
+  fi
+
+  # Linux - use notify-send
+  if command -v notify-send &>/dev/null; then
+    notify-send "${title}" "${message}" 2>/dev/null
+    return 0
+  fi
+
+  # Fallback - just print to console
+  echo "[NOTIFICATION] ${title}: ${message}"
+}
+
+# Build notification message
+if [ -n "$MR_URL" ]; then
+  MESSAGE="${TITLE} - Ready for review"
+else
+  MESSAGE="${TITLE} - Work complete"
+fi
+
+send_notification "Panopticon: ${ISSUE_ID}" "$MESSAGE"
+
+echo "Notification sent for ${ISSUE_ID}"

package/scripts/postinstall.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script for Panopticon
+ *
+ * Automatically syncs hooks after npm install/upgrade if Panopticon
+ * has been initialized (bin dir exists).
+ */
+
+import { existsSync, readdirSync, copyFileSync, chmodSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BIN_DIR = join(homedir(), '.panopticon', 'bin');
+const SCRIPTS_DIR = __dirname;
+
+// Only run if Panopticon has been initialized
+if (!existsSync(join(homedir(), '.panopticon'))) {
+  console.log('Panopticon not initialized yet. Run `pan init` to set up.');
+  process.exit(0);
+}
+
+// Ensure bin directory exists
+mkdirSync(BIN_DIR, { recursive: true });
+
+// Copy all scripts from scripts/ to ~/.panopticon/bin/
+const scripts = readdirSync(SCRIPTS_DIR)
+  .filter(f => !f.startsWith('.') && !f.endsWith('.mjs') && !f.endsWith('.js'));
+
+let synced = 0;
+for (const script of scripts) {
+  try {
+    const source = join(SCRIPTS_DIR, script);
+    const target = join(BIN_DIR, script);
+    copyFileSync(source, target);
+    chmodSync(target, 0o755);
+    synced++;
+  } catch (e) {
+    // Ignore errors, hooks are non-critical
+  }
+}
+
+if (synced > 0) {
+  console.log(`✓ Synced ${synced} hooks to ~/.panopticon/bin/`);
+}
+
+// Suggest running full sync
+console.log('Run `pan sync` to sync skills and commands to AI tools.');

package/scripts/pre-tool-hook

@@ -0,0 +1,60 @@
+#!/bin/bash
+# ~/.panopticon/bin/pre-tool-hook
+# Called by Claude Code before every tool use
+#
+# This hook sets agent state to "active" and optionally sends
+# heartbeat to API server for real-time dashboard updates
+
+# Don't use set -e - we want the hook to be resilient to failures
+# and never break Claude Code execution
+
+# Get agent ID from env (set by pan work issue) or tmux session name
+if [ -n "$PANOPTICON_AGENT_ID" ]; then
+  AGENT_ID="$PANOPTICON_AGENT_ID"
+elif [ -n "$TMUX" ]; then
+  AGENT_ID=$(tmux display-message -p '#S' 2>/dev/null)
+else
+  AGENT_ID="main-cli"
+fi
+AGENT_ID="${AGENT_ID:-unknown}"
+
+# Parse tool info from stdin
+TOOL_INFO=$(cat 2>/dev/null || echo '{}')
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+  exit 0  # Silent failure - don't break Claude Code execution
+fi
+
+# Extract tool name
+TOOL_NAME=$(echo "$TOOL_INFO" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")
+
+# Ensure state directory exists
+STATE_DIR="$HOME/.panopticon/agents/$AGENT_ID"
+mkdir -p "$STATE_DIR"
+
+# Write state to file (atomic write via temp file)
+TEMP_FILE="$STATE_DIR/state.json.tmp"
+jq -n \
+  --arg timestamp "$(date -Iseconds)" \
+  --arg state "active" \
+  --arg tool "$TOOL_NAME" \
+  '{
+    state: $state,
+    lastActivity: $timestamp,
+    currentTool: $tool
+  }' > "$TEMP_FILE" 2>/dev/null || true
+
+mv "$TEMP_FILE" "$STATE_DIR/state.json" 2>/dev/null || true
+
+# Optionally send heartbeat to API server (non-blocking)
+# Only if dashboard is running
+if curl -s -f --max-time 0.5 "http://localhost:3011/health" > /dev/null 2>&1; then
+  curl -s -X POST "http://localhost:3011/api/agents/$AGENT_ID/heartbeat" \
+    -H "Content-Type: application/json" \
+    -d "{\"state\":\"active\",\"tool\":\"$TOOL_NAME\",\"timestamp\":\"$(date -Iseconds)\"}" \
+    > /dev/null 2>&1 &
+fi
+
+# Always exit successfully
+exit 0

package/scripts/record-cost-event.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Record a cost event from Claude Code tool usage
+ * Called by heartbeat-hook with JSON input on stdin
+ */
+
+import { readFileSync } from 'fs';
+import { calculateCost, getPricing } from '../src/lib/cost.js';
+import { appendCostEvent } from '../src/lib/costs/events.js';
+
+// Read tool info from stdin
+let toolInfo;
+try {
+  const input = readFileSync(0, 'utf-8');
+  toolInfo = JSON.parse(input);
+} catch (err) {
+  // Silent failure - don't break Claude Code execution
+  process.exit(0);
+}
+
+// Extract usage data from tool info
+const usage = toolInfo?.usage || toolInfo?.message?.usage;
+if (!usage) {
+  // No usage data - not a Claude API call
+  process.exit(0);
+}
+
+// Extract token counts
+const inputTokens = usage.input_tokens || 0;
+const outputTokens = usage.output_tokens || 0;
+const cacheReadTokens = usage.cache_read_input_tokens || 0;
+const cacheWriteTokens = usage.cache_creation_input_tokens || 0;
+
+// Must have at least some tokens to record
+if (inputTokens === 0 && outputTokens === 0 && cacheReadTokens === 0 && cacheWriteTokens === 0) {
+  process.exit(0);
+}
+
+// Extract model name
+const model = toolInfo?.model || toolInfo?.message?.model || 'claude-sonnet-4';
+
+// Determine provider from model name
+let provider = 'anthropic';
+if (model.includes('gpt')) {
+  provider = 'openai';
+} else if (model.includes('gemini')) {
+  provider = 'google';
+}
+
+// Get pricing and calculate cost
+const pricing = getPricing(provider, model);
+if (!pricing) {
+  console.warn(`No pricing found for ${provider}/${model}`);
+  process.exit(0);
+}
+
+const cost = calculateCost({
+  inputTokens,
+  outputTokens,
+  cacheReadTokens,
+  cacheWriteTokens,
+  cacheTTL: '5m',
+}, pricing);
+
+// Get agent and issue context from environment
+// PANOPTICON_AGENT_ID should always be set by pan work or heartbeat-hook
+// If not set, use a fallback that makes it clear costs are unattributed
+const agentId = process.env.PANOPTICON_AGENT_ID || 'unattributed';
+
+const issueId = process.env.PANOPTICON_ISSUE_ID || 'UNKNOWN';
+const sessionType = process.env.PANOPTICON_SESSION_TYPE || 'implementation';
+
+// Record cost event
+try {
+  appendCostEvent({
+    ts: new Date().toISOString(),
+    type: 'cost',
+    agentId,
+    issueId,
+    sessionType,
+    provider,
+    model,
+    input: inputTokens,
+    output: outputTokens,
+    cacheRead: cacheReadTokens,
+    cacheWrite: cacheWriteTokens,
+    cost,
+  });
+} catch (err) {
+  // Silent failure - don't break Claude Code execution
+  console.error('Failed to record cost event:', err);
+}
+
+process.exit(0);

package/scripts/record-cost-event.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Record a cost event from Claude Code tool usage
+ * Called by heartbeat-hook with JSON input on stdin
+ */
+
+import { readFileSync } from 'fs';
+import { calculateCost, getPricing, AIProvider } from '../src/lib/cost.js';
+import { appendCostEvent } from '../src/lib/costs/events.js';
+
+// ============== Types ==============
+
+interface UsageData {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_read_input_tokens?: number;
+  cache_creation_input_tokens?: number;
+}
+
+interface ToolInfo {
+  model?: string;
+  usage?: UsageData;
+  message?: {
+    model?: string;
+    usage?: UsageData;
+  };
+}
+
+// ============== Main ==============
+
+// Read tool info from stdin
+let toolInfo: ToolInfo;
+try {
+  const input = readFileSync(0, 'utf-8');
+  toolInfo = JSON.parse(input) as ToolInfo;
+} catch (err) {
+  // Silent failure - don't break Claude Code execution
+  process.exit(0);
+}
+
+// Extract usage data from tool info
+const usage: UsageData | undefined = toolInfo?.usage || toolInfo?.message?.usage;
+if (!usage) {
+  // No usage data - not a Claude API call
+  process.exit(0);
+}
+
+// Extract token counts
+const inputTokens = usage.input_tokens || 0;
+const outputTokens = usage.output_tokens || 0;
+const cacheReadTokens = usage.cache_read_input_tokens || 0;
+const cacheWriteTokens = usage.cache_creation_input_tokens || 0;
+
+// Must have at least some tokens to record
+if (inputTokens === 0 && outputTokens === 0 && cacheReadTokens === 0 && cacheWriteTokens === 0) {
+  process.exit(0);
+}
+
+// Extract model name
+const model: string = toolInfo?.model || toolInfo?.message?.model || 'claude-sonnet-4';
+
+// Determine provider from model name
+let provider: AIProvider = 'anthropic';
+if (model.includes('gpt')) {
+  provider = 'openai';
+} else if (model.includes('gemini')) {
+  provider = 'google';
+}
+
+// Get pricing and calculate cost
+const pricing = getPricing(provider, model);
+if (!pricing) {
+  console.warn(`No pricing found for ${provider}/${model}`);
+  process.exit(0);
+}
+
+const cost = calculateCost({
+  inputTokens,
+  outputTokens,
+  cacheReadTokens,
+  cacheWriteTokens,
+  cacheTTL: '5m',
+}, pricing);
+
+// Get agent and issue context from environment
+// PANOPTICON_AGENT_ID should always be set by pan work or heartbeat-hook
+// If not set, use a fallback that makes it clear costs are unattributed
+const agentId: string = process.env.PANOPTICON_AGENT_ID || 'unattributed';
+const issueId: string = process.env.PANOPTICON_ISSUE_ID || 'UNKNOWN';
+const sessionType: string = process.env.PANOPTICON_SESSION_TYPE || 'implementation';
+
+// Record cost event
+try {
+  appendCostEvent({
+    ts: new Date().toISOString(),
+    type: 'cost',
+    agentId,
+    issueId,
+    sessionType,
+    provider,
+    model,
+    input: inputTokens,
+    output: outputTokens,
+    cacheRead: cacheReadTokens,
+    cacheWrite: cacheWriteTokens,
+    cost,
+  });
+} catch (err) {
+  // Silent failure - don't break Claude Code execution
+  console.error('Failed to record cost event:', err);
+}
+
+process.exit(0);

package/scripts/restart-dashboard.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Restart Panopticon dashboard cleanly
+# Usage: ./restart-dashboard.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DASHBOARD_DIR="$SCRIPT_DIR/../src/dashboard"
+LOG_FILE="/tmp/panopticon-dashboard.log"
+
+echo "Stopping dashboard..."
+
+# Most reliable: kill by port using fuser -k
+for port in 3010 3011 3012; do
+  fuser -k ${port}/tcp 2>/dev/null || true
+done
+
+# Also kill any npm/node processes that might be orphaned
+pkill -9 -f "npm.*dashboard" 2>/dev/null || true
+pkill -9 -f "node.*panopticon.*dashboard" 2>/dev/null || true
+pkill -9 -f "vite.*301" 2>/dev/null || true
+pkill -9 -f "concurrently.*dev:server" 2>/dev/null || true
+
+sleep 2
+
+# Verify ports are clear
+if lsof -i :3010,:3011,:3012 >/dev/null 2>&1; then
+  echo "Warning: Ports still in use, force killing..."
+  lsof -ti :3010,:3011,:3012 | xargs -r kill -9 2>/dev/null || true
+  sleep 1
+fi
+
+echo "Starting dashboard..."
+
+cd "$DASHBOARD_DIR"
+rm -f "$LOG_FILE"
+
+# Use setsid to fully detach from terminal
+setsid npm run dev > "$LOG_FILE" 2>&1 &
+
+# Wait for API to be ready
+echo -n "Waiting for API"
+for i in {1..30}; do
+  if curl -s --max-time 2 http://localhost:3011/api/health > /dev/null 2>&1; then
+    echo ""
+    echo "Dashboard ready!"
+    echo "  Frontend: http://localhost:3010"
+    echo "  API:      http://localhost:3011"
+    echo "  Logs:     $LOG_FILE"
+    exit 0
+  fi
+  echo -n "."
+  sleep 1
+done
+
+echo ""
+echo "ERROR: API not responding after 30s"
+echo "Check logs: tail -50 $LOG_FILE"
+exit 1

package/scripts/setup-certs.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# Setup local HTTPS certificates for Panopticon using mkcert
+# This script generates trusted certificates for *.pan.localhost
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CERTS_DIR="${SCRIPT_DIR}/../templates/traefik/certs"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo "Setting up local HTTPS certificates for Panopticon..."
+
+# Check if mkcert is installed
+if ! command -v mkcert &> /dev/null; then
+    echo -e "${RED}Error: mkcert is not installed.${NC}"
+    echo ""
+    echo "Install mkcert first:"
+    echo "  macOS:   brew install mkcert"
+    echo "  Linux:   apt install mkcert  OR  brew install mkcert"
+    echo "  Windows: choco install mkcert"
+    echo ""
+    echo "More info: https://github.com/FiloSottile/mkcert"
+    exit 1
+fi
+
+echo -e "${GREEN}mkcert found at $(which mkcert)${NC}"
+
+# Check if CA is installed
+CAROOT=$(mkcert -CAROOT 2>/dev/null)
+if [ -f "$CAROOT/rootCA.pem" ]; then
+    echo -e "${GREEN}Local CA already exists at $CAROOT${NC}"
+else
+    echo -e "${YELLOW}Installing local CA...${NC}"
+    echo "This may require sudo password to add CA to system trust store."
+    mkcert -install
+    echo -e "${GREEN}CA installed successfully${NC}"
+fi
+
+# Create certs directory if it doesn't exist
+mkdir -p "$CERTS_DIR"
+
+# Generate certificates for pan.localhost
+echo ""
+echo "Generating certificates for *.pan.localhost..."
+cd "$CERTS_DIR"
+
+# Generate wildcard cert for pan.localhost
+mkcert -cert-file "_wildcard.pan.localhost.pem" \
+       -key-file "_wildcard.pan.localhost-key.pem" \
+       "pan.localhost" "*.pan.localhost"
+
+echo ""
+echo -e "${GREEN}Certificates generated successfully!${NC}"
+echo ""
+echo "Certificate files:"
+ls -la "$CERTS_DIR"/*.pem
+echo ""
+echo "You can now start Traefik:"
+echo "  cd templates/traefik && docker compose up -d"
+echo ""
+echo "Access the dashboard at: https://pan.localhost"

package/scripts/specialist-stop-hook

@@ -0,0 +1,106 @@
+#!/bin/bash
+# ~/.panopticon/bin/specialist-stop-hook
+# Called when a specialist agent goes idle - detects completion patterns
+#
+# This hook is chained from stop-hook and only runs for specialist agents.
+# It captures the last 50 lines of terminal output and looks for completion
+# patterns to auto-trigger status updates.
+
+# Don't use set -e - we want the hook to be resilient to failures
+# and never break Claude Code execution
+
+# Get agent ID from env or tmux session name
+if [ -n "$PANOPTICON_AGENT_ID" ]; then
+  AGENT_ID="$PANOPTICON_AGENT_ID"
+elif [ -n "$TMUX" ]; then
+  AGENT_ID=$(tmux display-message -p '#S' 2>/dev/null)
+else
+  exit 0  # Not in a tracked session
+fi
+
+# Check if this is a specialist agent
+case "$AGENT_ID" in
+  specialist-review-agent|specialist-test-agent|specialist-merge-agent)
+    ;;
+  *)
+    exit 0  # Not a specialist, skip
+    ;;
+esac
+
+# Get the specialist type from agent ID
+SPECIALIST_TYPE="${AGENT_ID#specialist-}"
+
+# Capture the last 50 lines of terminal output
+OUTPUT=$(tmux capture-pane -t "$AGENT_ID" -p -S -50 2>/dev/null || echo "")
+
+if [ -z "$OUTPUT" ]; then
+  exit 0  # No output to analyze
+fi
+
+# Define completion patterns for each specialist (case-insensitive grep -E patterns)
+case "$SPECIALIST_TYPE" in
+  review-agent)
+    # Patterns that indicate review passed
+    PASS_PATTERN="[Rr]eview (passed|complete|PASSED|COMPLETE)|LGTM|[Nn]o issues found|[Cc]ode review complete|✓.*[Pp]assed"
+    # Patterns that indicate review failed/blocked
+    FAIL_PATTERN="[Rr]eview (failed|blocked|FAILED|BLOCKED)|[Ii]ssues found|[Nn]eeds changes|[Bb]locked"
+    STATUS_FIELD="reviewStatus"
+    ;;
+  test-agent)
+    # Patterns that indicate tests passed
+    PASS_PATTERN="(all )?[Tt]ests? passed|test suite passed|0 failed|✓.*[Pp]assed|Tests PASSED"
+    # Patterns that indicate tests failed
+    FAIL_PATTERN="[Tt]ests? failed|test failures|[0-9]+ failed|✗.*[Ff]ailed|Tests FAILED"
+    STATUS_FIELD="testStatus"
+    ;;
+  merge-agent)
+    # Patterns that indicate merge complete
+    PASS_PATTERN="[Mm]erge (complete|successful)|[Pp]ushed to|[Mm]erged to main|[Mm]erged successfully"
+    # Patterns that indicate merge failed
+    FAIL_PATTERN="[Mm]erge conflict|[Cc]annot merge|[Mm]erge failed"
+    STATUS_FIELD="mergeStatus"
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Check for completion patterns (look at output)
+STATUS=""
+if echo "$OUTPUT" | grep -qE "$PASS_PATTERN"; then
+  STATUS="passed"
+elif echo "$OUTPUT" | grep -qE "$FAIL_PATTERN"; then
+  STATUS="failed"
+fi
+
+if [ -z "$STATUS" ]; then
+  exit 0  # No recognized completion pattern - specialist is just idle
+fi
+
+# Get current issue from specialist state file
+STATE_FILE="$HOME/.panopticon/agents/$AGENT_ID/state.json"
+ISSUE_ID=""
+
+if [ -f "$STATE_FILE" ] && command -v jq &> /dev/null; then
+  ISSUE_ID=$(jq -r '.currentIssue // ""' "$STATE_FILE" 2>/dev/null || echo "")
+fi
+
+if [ -z "$ISSUE_ID" ] || [ "$ISSUE_ID" = "null" ]; then
+  # No issue ID - cannot report completion
+  exit 0
+fi
+
+# Report completion to dashboard API (non-blocking background process)
+# Only if dashboard is running
+if curl -s -f --max-time 0.5 "http://localhost:3011/health" > /dev/null 2>&1; then
+  curl -s -X POST "http://localhost:3011/api/specialists/$SPECIALIST_TYPE/auto-complete" \
+    -H "Content-Type: application/json" \
+    -d "{\"issueId\":\"$ISSUE_ID\",\"status\":\"$STATUS\"}" \
+    > /dev/null 2>&1 &
+
+  # Log the completion detection
+  echo "[specialist-stop-hook] Detected completion: $SPECIALIST_TYPE -> $ISSUE_ID -> $STATUS" \
+    >> "$HOME/.panopticon/logs/hooks.log" 2>/dev/null || true
+fi
+
+exit 0

package/scripts/stop-hook

@@ -0,0 +1,58 @@
+#!/bin/bash
+# ~/.panopticon/bin/stop-hook
+# Called by Claude Code when it finishes responding (waiting for input)
+#
+# This hook sets agent state to "idle" for auto-suspend detection
+
+# Don't use set -e - we want the hook to be resilient to failures
+# and never break Claude Code execution
+
+# Get agent ID from env (set by pan work issue) or tmux session name
+if [ -n "$PANOPTICON_AGENT_ID" ]; then
+  AGENT_ID="$PANOPTICON_AGENT_ID"
+elif [ -n "$TMUX" ]; then
+  AGENT_ID=$(tmux display-message -p '#S' 2>/dev/null)
+else
+  AGENT_ID="main-cli"
+fi
+AGENT_ID="${AGENT_ID:-unknown}"
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+  exit 0  # Silent failure - don't break Claude Code execution
+fi
+
+# Ensure state directory exists
+STATE_DIR="$HOME/.panopticon/agents/$AGENT_ID"
+mkdir -p "$STATE_DIR"
+
+# Write state to file (atomic write via temp file)
+TEMP_FILE="$STATE_DIR/state.json.tmp"
+jq -n \
+  --arg timestamp "$(date -Iseconds)" \
+  --arg state "idle" \
+  '{
+    state: $state,
+    lastActivity: $timestamp
+  }' > "$TEMP_FILE" 2>/dev/null || true
+
+mv "$TEMP_FILE" "$STATE_DIR/state.json" 2>/dev/null || true
+
+# Optionally send heartbeat to API server (non-blocking)
+# Only if dashboard is running
+if curl -s -f --max-time 0.5 "http://localhost:3011/health" > /dev/null 2>&1; then
+  curl -s -X POST "http://localhost:3011/api/agents/$AGENT_ID/heartbeat" \
+    -H "Content-Type: application/json" \
+    -d "{\"state\":\"idle\",\"timestamp\":\"$(date -Iseconds)\"}" \
+    > /dev/null 2>&1 &
+fi
+
+# Chain to specialist-specific hook for auto-completion detection
+# This runs in background and only affects specialist agents
+SPECIALIST_HOOK="$HOME/.panopticon/bin/specialist-stop-hook"
+if [ -x "$SPECIALIST_HOOK" ]; then
+  "$SPECIALIST_HOOK" &
+fi
+
+# Always exit successfully
+exit 0

package/scripts/validate-merge.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# validate-merge.sh - Validation script for merge completeness
+# Checks for conflict markers, runs build, and runs tests
+# Usage: validate-merge.sh [PROJECT_ROOT]
+# Exit codes: 0 = validation passed, 1 = validation failed
+
+set -e
+
+PROJECT_ROOT="${1:-.}"
+cd "$PROJECT_ROOT"
+
+echo "=== Merge Validation ==="
+echo "Project root: $(pwd)"
+echo ""
+
+# 1. Check for conflict markers
+echo "Checking for conflict markers..."
+CONFLICT_FOUND=false
+
+# Check for <<<<<<< markers (at start of line only)
+if git grep -l '^<<<<<<< ' 2>/dev/null; then
+    echo "ERROR: Conflict start markers found in files:"
+    git grep -l '^<<<<<<< '
+    CONFLICT_FOUND=true
+fi
+
+# Check for ======= markers (at start of line)
+if git grep -l '^=======$' 2>/dev/null; then
+    echo "ERROR: Conflict separator markers found in files:"
+    git grep -l '^=======$'
+    CONFLICT_FOUND=true
+fi
+
+# Check for >>>>>>> markers (at start of line only)
+if git grep -l '^>>>>>>> ' 2>/dev/null; then
+    echo "ERROR: Conflict end markers found in files:"
+    git grep -l '^>>>>>>> '
+    CONFLICT_FOUND=true
+fi
+
+if [ "$CONFLICT_FOUND" = true ]; then
+    echo ""
+    echo "VALIDATION FAILED: Conflict markers detected"
+    exit 1
+fi
+
+echo "✓ No conflict markers found"
+echo ""
+
+# 2. Run build
+echo "Running build..."
+if [ -f "package.json" ]; then
+    if npm run build 2>&1; then
+        echo "✓ Build passed"
+    else
+        echo ""
+        echo "VALIDATION FAILED: Build errors detected"
+        exit 1
+    fi
+elif [ -f "pom.xml" ]; then
+    if mvn compile 2>&1; then
+        echo "✓ Build passed"
+    else
+        echo ""
+        echo "VALIDATION FAILED: Build errors detected"
+        exit 1
+    fi
+else
+    echo "⚠ No build system detected (no package.json or pom.xml), skipping build check"
+fi
+echo ""
+
+# 3. Run tests
+# BASELINE_FAILURES env var enables baseline comparison mode:
+# If set, only fail when NEW failures appear (failures > baseline)
+echo "Running tests..."
+if [ -n "$BASELINE_FAILURES" ]; then
+    echo "Baseline comparison mode: $BASELINE_FAILURES pre-existing failures"
+fi
+
+if [ -f "package.json" ]; then
+    TEST_OUTPUT=$(npm test 2>&1) || true
+    echo "$TEST_OUTPUT"
+
+    # Check if tests passed cleanly
+    if echo "$TEST_OUTPUT" | grep -q "Tests.*passed\|0 failed"; then
+        echo "✓ Tests passed"
+    elif [ -n "$BASELINE_FAILURES" ]; then
+        # Baseline mode: extract failure count and compare
+        # Match vitest output format: "X failed" or "X tests failed"
+        ACTUAL_FAILURES=$(echo "$TEST_OUTPUT" | grep -oP '(\d+)\s+failed' | head -1 | grep -oP '\d+' || echo "0")
+        if [ "$ACTUAL_FAILURES" -le "$BASELINE_FAILURES" ]; then
+            echo ""
+            echo "✓ Tests passed (baseline comparison: $ACTUAL_FAILURES failures <= $BASELINE_FAILURES baseline)"
+        else
+            echo ""
+            echo "VALIDATION FAILED: New test failures detected ($ACTUAL_FAILURES > baseline $BASELINE_FAILURES)"
+            exit 1
+        fi
+    else
+        echo ""
+        echo "VALIDATION FAILED: Test failures detected"
+        exit 1
+    fi
+elif [ -f "pom.xml" ]; then
+    if mvn test 2>&1; then
+        echo "✓ Tests passed"
+    else
+        echo ""
+        echo "VALIDATION FAILED: Test failures detected"
+        exit 1
+    fi
+else
+    echo "⚠ No test system detected, skipping test check"
+fi
+echo ""
+
+echo "=== VALIDATION PASSED ==="
+exit 0