pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/infrastructure/watchdog/__tests__/.audit-reports/token-monitor.log

@@ -0,0 +1,18 @@
+{"timestamp":"2025-12-28T13:51:42.311Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"ok","percentUsed":10,"tokensUsed":100000,"maxTokens":1000000,"source":"realtime","stale":false},"context":{"message":"Result level=ok percent=10% used=100000/1000000 source=realtime"}}
+{"timestamp":"2025-12-28T13:51:42.313Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"warning","percentUsed":91,"tokensUsed":910000,"maxTokens":1000000,"source":"fallback","stale":false},"context":{"message":"Result level=warning percent=91% used=910000/1000000 source=fallback"}}
+{"timestamp":"2025-12-28T13:51:42.313Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"critical","percentUsed":98,"tokensUsed":980000,"maxTokens":1000000,"source":"realtime","stale":true},"context":{"message":"Result level=critical percent=98% used=980000/1000000 source=realtime (stale)"}}
+{"timestamp":"2025-12-28T13:53:16.019Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"ok","percentUsed":10,"tokensUsed":100000,"maxTokens":1000000,"source":"realtime","stale":false},"context":{"message":"Result level=ok percent=10% used=100000/1000000 source=realtime"}}
+{"timestamp":"2025-12-28T13:53:16.021Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"warning","percentUsed":91,"tokensUsed":910000,"maxTokens":1000000,"source":"fallback","stale":false},"context":{"message":"Result level=warning percent=91% used=910000/1000000 source=fallback"}}
+{"timestamp":"2025-12-28T13:53:16.022Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"critical","percentUsed":98,"tokensUsed":980000,"maxTokens":1000000,"source":"realtime","stale":true},"context":{"message":"Result level=critical percent=98% used=980000/1000000 source=realtime (stale)"}}
+{"timestamp":"2025-12-28T13:55:27.087Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"ok","percentUsed":10,"tokensUsed":100000,"maxTokens":1000000,"source":"realtime","stale":false},"context":{"message":"Result level=ok percent=10% used=100000/1000000 source=realtime"}}
+{"timestamp":"2025-12-28T13:55:27.090Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"warning","percentUsed":91,"tokensUsed":910000,"maxTokens":1000000,"source":"fallback","stale":false},"context":{"message":"Result level=warning percent=91% used=910000/1000000 source=fallback"}}
+{"timestamp":"2025-12-28T13:55:27.090Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"critical","percentUsed":98,"tokensUsed":980000,"maxTokens":1000000,"source":"realtime","stale":true},"context":{"message":"Result level=critical percent=98% used=980000/1000000 source=realtime (stale)"}}
+{"timestamp":"2025-12-28T13:56:39.046Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"ok","percentUsed":10,"tokensUsed":100000,"maxTokens":1000000,"source":"realtime","stale":false},"context":{"message":"Result level=ok percent=10% used=100000/1000000 source=realtime"}}
+{"timestamp":"2025-12-28T13:56:39.050Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"warning","percentUsed":91,"tokensUsed":910000,"maxTokens":1000000,"source":"fallback","stale":false},"context":{"message":"Result level=warning percent=91% used=910000/1000000 source=fallback"}}
+{"timestamp":"2025-12-28T13:56:39.051Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"critical","percentUsed":98,"tokensUsed":980000,"maxTokens":1000000,"source":"realtime","stale":true},"context":{"message":"Result level=critical percent=98% used=980000/1000000 source=realtime (stale)"}}
+{"timestamp":"2025-12-28T13:57:17.547Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"ok","percentUsed":10,"tokensUsed":100000,"maxTokens":1000000,"source":"realtime","stale":false},"context":{"message":"Result level=ok percent=10% used=100000/1000000 source=realtime"}}
+{"timestamp":"2025-12-28T13:57:17.549Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"warning","percentUsed":91,"tokensUsed":910000,"maxTokens":1000000,"source":"fallback","stale":false},"context":{"message":"Result level=warning percent=91% used=910000/1000000 source=fallback"}}
+{"timestamp":"2025-12-28T13:57:17.550Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"critical","percentUsed":98,"tokensUsed":980000,"maxTokens":1000000,"source":"realtime","stale":true},"context":{"message":"Result level=critical percent=98% used=980000/1000000 source=realtime (stale)"}}
+{"timestamp":"2025-12-28T13:58:29.678Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"ok","percentUsed":10,"tokensUsed":100000,"maxTokens":1000000,"source":"realtime","stale":false},"context":{"message":"Result level=ok percent=10% used=100000/1000000 source=realtime"}}
+{"timestamp":"2025-12-28T13:58:29.681Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"warning","percentUsed":91,"tokensUsed":910000,"maxTokens":1000000,"source":"fallback","stale":false},"context":{"message":"Result level=warning percent=91% used=910000/1000000 source=fallback"}}
+{"timestamp":"2025-12-28T13:58:29.682Z","level":"info","component":"TokenMonitor","event":"TOKEN_MONITOR_RESULT","data":{"level":"critical","percentUsed":98,"tokensUsed":980000,"maxTokens":1000000,"source":"realtime","stale":true},"context":{"message":"Result level=critical percent=98% used=980000/1000000 source=realtime (stale)"}}

package/scripts/hooks-system/infrastructure/watchdog/__tests__/auto-recovery.spec.js

@@ -0,0 +1,14 @@
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+describe('auto-recovery CLI', () => {
+    it('runs without errors and writes logs', () => {
+        const script = path.join(__dirname, '..', 'auto-recovery.js');
+        const result = spawnSync('node', [script, 'test-reason', 'guard'], {
+            cwd: path.join(__dirname, '../../..'),
+            stdio: 'pipe'
+        });
+
+        expect(result.status).toBe(0);
+    });
+});

package/scripts/hooks-system/infrastructure/watchdog/__tests__/token-monitor.spec.js

@@ -0,0 +1,67 @@
+const { runTokenMonitor } = require('../token-monitor');
+
+describe('token-monitor CLI', () => {
+    it('debe retornar exitCode 0 cuando el nivel es ok', async () => {
+        const service = {
+            run: jest.fn().mockResolvedValue({
+                level: 'ok',
+                tokensUsed: 100000,
+                maxTokens: 1_000_000,
+                percentUsed: 10,
+                source: 'realtime',
+                stale: false
+            })
+        };
+
+        const result = await runTokenMonitor({
+            repoRoot: __dirname,
+            service,
+            notificationCenter: { shutdown: jest.fn() }
+        });
+
+        expect(result.exitCode).toBe(0);
+        expect(service.run).toHaveBeenCalled();
+    });
+
+    it('debe retornar exitCode 1 cuando el nivel es warning', async () => {
+        const service = {
+            run: jest.fn().mockResolvedValue({
+                level: 'warning',
+                tokensUsed: 910000,
+                maxTokens: 1_000_000,
+                percentUsed: 91,
+                source: 'fallback',
+                stale: false
+            })
+        };
+
+        const result = await runTokenMonitor({
+            repoRoot: __dirname,
+            service,
+            notificationCenter: { shutdown: jest.fn() }
+        });
+
+        expect(result.exitCode).toBe(1);
+    });
+
+    it('debe retornar exitCode 2 cuando el nivel es crítico', async () => {
+        const service = {
+            run: jest.fn().mockResolvedValue({
+                level: 'critical',
+                tokensUsed: 980000,
+                maxTokens: 1_000_000,
+                percentUsed: 98,
+                source: 'realtime',
+                stale: true
+            })
+        };
+
+        const result = await runTokenMonitor({
+            repoRoot: __dirname,
+            service,
+            notificationCenter: { shutdown: jest.fn() }
+        });
+
+        expect(result.exitCode).toBe(2);
+    });
+});

package/scripts/hooks-system/infrastructure/watchdog/__tests__/watchdog.spec.js

@@ -0,0 +1,22 @@
+describe('watchdog', () => {
+    describe('auto-recovery', () => {
+        it('should export module', () => {
+            const mod = require('../auto-recovery');
+            expect(mod).toBeDefined();
+        });
+    });
+
+    describe('health-check', () => {
+        it('should export module', () => {
+            const mod = require('../health-check');
+            expect(mod).toBeDefined();
+        });
+    });
+
+    describe('token-monitor', () => {
+        it('should export module', () => {
+            const mod = require('../token-monitor');
+            expect(mod).toBeDefined();
+        });
+    });
+});

package/scripts/hooks-system/infrastructure/watchdog/ai-watchdog.sh

@@ -0,0 +1,278 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════
+# AI Watchdog - Background File Monitor (Proactive)
+# ═══════════════════════════════════════════════════════════════
+# Monitors file changes and validates .AI_EVIDENCE.json freshness
+# Usage: bash ai-watchdog.sh start|stop|status
+#
+# This runs in background and alerts BEFORE you commit if evidence
+# is stale (>10 minutes old).
+# ═══════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# Paths
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+EVIDENCE_FILE="$REPO_ROOT/.AI_EVIDENCE.json"
+WATCHDOG_PID_FILE="$REPO_ROOT/.ai-watchdog.pid"
+WATCHDOG_LOG="$REPO_ROOT/.audit-reports/watchdog.log"
+
+# Max evidence age (seconds)
+MAX_EVIDENCE_AGE=180  # 3 minutes (configurable - adjust based on your workflow)
+
+#───────────────────────────────────────────────────────────────
+# Check if fswatch is installed
+#───────────────────────────────────────────────────────────────
+check_fswatch() {
+  if ! command -v fswatch &> /dev/null; then
+    echo -e "${YELLOW}⚠️  fswatch not installed${NC}"
+    echo ""
+    echo "Install with:"
+    echo "  macOS: brew install fswatch"
+    echo "  Linux: apt-get install fswatch"
+    echo ""
+    return 1
+  fi
+  return 0
+}
+
+#───────────────────────────────────────────────────────────────
+# Check evidence freshness
+#───────────────────────────────────────────────────────────────
+check_evidence() {
+  if [[ ! -f "$EVIDENCE_FILE" ]]; then
+    echo -e "${RED}❌ .AI_EVIDENCE.json NOT FOUND${NC}"
+    echo ""
+    echo "Run: ai-start feature-name"
+    echo ""
+    return 1
+  fi
+
+  # Get evidence timestamp
+  local evidence_ts=$(jq -r '.timestamp' "$EVIDENCE_FILE" 2>/dev/null || echo "")
+
+  if [[ -z "$evidence_ts" ]] || [[ "$evidence_ts" == "null" ]]; then
+    echo -e "${RED}❌ Evidence missing timestamp${NC}"
+    return 1
+  fi
+
+  # Convert to epoch (handle ISO 8601 with milliseconds)
+  # Remove milliseconds if present: 2025-11-06T06:16:40.179Z → 2025-11-06T06:16:40Z
+  local clean_ts=$(echo "$evidence_ts" | sed 's/\.[0-9]*Z$/Z/')
+  local evidence_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$clean_ts" +%s 2>/dev/null || echo "0")
+  local now_epoch=$(date +%s)
+  local age=$((now_epoch - evidence_epoch))
+
+  if [[ $age -gt $MAX_EVIDENCE_AGE ]]; then
+    echo -e "${RED}❌ Evidence is STALE (${age}s old, max ${MAX_EVIDENCE_AGE}s)${NC}"
+    echo ""
+    echo "Run: ai-start feature-name"
+    echo ""
+    return 1
+  fi
+
+  echo -e "${GREEN}✅ Evidence fresh (${age}s old)${NC}"
+  return 0
+}
+
+#───────────────────────────────────────────────────────────────
+# Periodic check (runs every 30s)
+#───────────────────────────────────────────────────────────────
+periodic_check() {
+  local last_notification=0
+  local notification_cooldown=300  # Don't spam notifications (5 min cooldown)
+
+  while true; do
+    sleep 30
+
+    if ! check_evidence >> "$WATCHDOG_LOG" 2>&1; then
+      local now=$(date +%s)
+      local time_since_last=$((now - last_notification))
+
+      # Only send notification if cooldown expired
+      if [[ $time_since_last -gt $notification_cooldown ]]; then
+        # Get current branch for notification
+        local current_branch=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+        # Send notification (macOS)
+        osascript -e "display notification \"Evidence is stale! Run: ai-start $current_branch\" with title \"🐕 AI Watchdog\" sound name \"Basso\"" 2>/dev/null || true
+
+        echo "$(date): ALERT - Evidence stale (periodic check)" >> "$WATCHDOG_LOG"
+        last_notification=$now
+      fi
+    fi
+  done
+}
+
+#───────────────────────────────────────────────────────────────
+# File change monitor (runs on file changes)
+#───────────────────────────────────────────────────────────────
+file_monitor() {
+  # Watch for file changes in key directories
+  fswatch -0 \
+    --exclude '\.git/' \
+    --exclude 'node_modules/' \
+    --exclude '\.next/' \
+    --exclude 'dist/' \
+    --exclude '\.audit-reports/' \
+    -e ".*" \
+    -i "\\.ts$" \
+    -i "\\.tsx$" \
+    -i "\\.js$" \
+    -i "\\.jsx$" \
+    -i "\\.swift$" \
+    -i "\\.kt$" \
+    "$REPO_ROOT/apps/" \
+    "$REPO_ROOT/CustomLintRules/" \
+    "$REPO_ROOT/custom-lint-rules/" 2>/dev/null | \
+  while read -d "" event; do
+    # Log event
+    echo "$(date): File changed: $event" >> "$WATCHDOG_LOG"
+
+    # Check evidence freshness
+    if ! check_evidence >> "$WATCHDOG_LOG" 2>&1; then
+      # Get current branch for notification
+      local current_branch=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+      # Send notification (macOS)
+      osascript -e "display notification \"Evidence is stale! Run: ai-start $current_branch\" with title \"🐕 AI Watchdog\" sound name \"Basso\"" 2>/dev/null || true
+
+      echo "$(date): ALERT - Evidence stale (file change)" >> "$WATCHDOG_LOG"
+    fi
+  done
+}
+
+#───────────────────────────────────────────────────────────────
+# Monitor function (runs both monitors in background)
+#───────────────────────────────────────────────────────────────
+monitor() {
+  mkdir -p "$(dirname "$WATCHDOG_LOG")"
+
+  echo "$(date): Watchdog started (PID $$)" >> "$WATCHDOG_LOG"
+  echo "$(date): Starting periodic check (every 30s)..." >> "$WATCHDOG_LOG"
+  echo "$(date): Starting file monitor..." >> "$WATCHDOG_LOG"
+
+  # Start periodic check in background
+  periodic_check &
+  local periodic_pid=$!
+
+  # Start file monitor (blocks here)
+  file_monitor
+
+  # If we reach here, file monitor died - kill periodic check
+  kill $periodic_pid 2>/dev/null || true
+}
+
+#───────────────────────────────────────────────────────────────
+# Start watchdog
+#───────────────────────────────────────────────────────────────
+start_watchdog() {
+  if [[ -f "$WATCHDOG_PID_FILE" ]]; then
+    local pid=$(cat "$WATCHDOG_PID_FILE")
+    if ps -p "$pid" > /dev/null 2>&1; then
+      echo -e "${YELLOW}⚠️  Watchdog already running (PID $pid)${NC}"
+      return 0
+    fi
+  fi
+
+  echo -e "${BLUE}🚀 Starting AI Watchdog...${NC}"
+
+  if ! check_fswatch; then
+    return 1
+  fi
+
+  # Start in background
+  nohup bash "$0" _monitor > /dev/null 2>&1 &
+  local pid=$!
+
+  echo "$pid" > "$WATCHDOG_PID_FILE"
+
+  echo -e "${GREEN}✅ Watchdog started (PID $pid)${NC}"
+  echo ""
+  echo "  Monitoring: apps/, CustomLintRules/, custom-lint-rules/"
+  echo "  Log: .audit-reports/watchdog.log"
+  echo ""
+  echo "Stop with: bash $(basename "$0") stop"
+}
+
+#───────────────────────────────────────────────────────────────
+# Stop watchdog
+#───────────────────────────────────────────────────────────────
+stop_watchdog() {
+  if [[ ! -f "$WATCHDOG_PID_FILE" ]]; then
+    echo -e "${YELLOW}⚠️  Watchdog not running${NC}"
+    return 0
+  fi
+
+  local pid=$(cat "$WATCHDOG_PID_FILE")
+
+  if ps -p "$pid" > /dev/null 2>&1; then
+    echo -e "${BLUE}🛑 Stopping watchdog (PID $pid)...${NC}"
+    kill "$pid" 2>/dev/null || true
+    rm "$WATCHDOG_PID_FILE"
+    echo -e "${GREEN}✅ Watchdog stopped${NC}"
+  else
+    echo -e "${YELLOW}⚠️  Watchdog not running (stale PID file)${NC}"
+    rm "$WATCHDOG_PID_FILE"
+  fi
+}
+
+#───────────────────────────────────────────────────────────────
+# Show status
+#───────────────────────────────────────────────────────────────
+show_status() {
+  echo -e "${BLUE}════════════════════════════════════════════════${NC}"
+  echo -e "${BLUE}🐕 AI WATCHDOG STATUS${NC}"
+  echo -e "${BLUE}════════════════════════════════════════════════${NC}"
+  echo ""
+
+  if [[ -f "$WATCHDOG_PID_FILE" ]]; then
+    local pid=$(cat "$WATCHDOG_PID_FILE")
+    if ps -p "$pid" > /dev/null 2>&1; then
+      echo -e "  Status: ${GREEN}RUNNING${NC}"
+      echo "  PID: $pid"
+      echo "  Log: .audit-reports/watchdog.log"
+      echo ""
+      check_evidence
+    else
+      echo -e "  Status: ${RED}STOPPED${NC} (stale PID)"
+      rm "$WATCHDOG_PID_FILE"
+    fi
+  else
+    echo -e "  Status: ${RED}STOPPED${NC}"
+  fi
+
+  echo ""
+  echo -e "${BLUE}════════════════════════════════════════════════${NC}"
+}
+
+#───────────────────────────────────────────────────────────────
+# Main
+#───────────────────────────────────────────────────────────────
+case "${1:-status}" in
+  start)
+    start_watchdog
+    ;;
+  stop)
+    stop_watchdog
+    ;;
+  status)
+    show_status
+    ;;
+  _monitor)
+    # Internal: run monitor (called by start)
+    monitor
+    ;;
+  *)
+    echo "Usage: $0 {start|stop|status}"
+    exit 1
+    ;;
+esac

package/scripts/hooks-system/infrastructure/watchdog/auto-recovery.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+const { createUnifiedLogger } = require('../logging/UnifiedLoggerFactory');
+const NotificationCenterService = require('../../application/services/notification/NotificationCenterService');
+const { AutoRecoveryManager } = require('../../application/services/recovery/AutoRecoveryManager');
+
+const repoRoot = process.env.HOOKS_REPO_ROOT ? path.resolve(process.env.HOOKS_REPO_ROOT) : process.cwd();
+const logger = createUnifiedLogger({
+    repoRoot,
+    component: 'AutoRecovery',
+    fileName: 'auto-recovery.log'
+});
+
+const notificationCenter = new NotificationCenterService({
+    repoRoot,
+    logger
+});
+
+const manager = new AutoRecoveryManager({
+    repoRoot,
+    logger,
+    notificationCenter
+});
+
+const reason = process.argv[2] || 'heartbeat-manual';
+const key = process.argv[3] || 'guard-supervisor';
+
+manager.recover({ key, reason }).finally(() => {
+    notificationCenter.shutdown();
+});

package/scripts/hooks-system/infrastructure/watchdog/health-check.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+const { createUnifiedLogger } = require('../logging/UnifiedLoggerFactory');
+const NotificationCenterService = require('../../application/services/notification/NotificationCenterService');
+const { HealthCheckService } = require('../../application/services/monitoring/HealthCheckService');
+const { getGitTreeState } = require('../../application/services/GitTreeState');
+const { createHealthCheckProviders } = require('../../application/services/monitoring/HealthCheckProviders');
+const path = require('path');
+
+async function runHealthCheck({ repoRoot = null } = {}) {
+    const resolvedRepoRoot = repoRoot
+        || (process.env.HOOKS_REPO_ROOT ? path.resolve(process.env.HOOKS_REPO_ROOT) : null)
+        || process.cwd();
+
+    const logger = createUnifiedLogger({
+        repoRoot: resolvedRepoRoot,
+        component: 'HealthCheck',
+        fileName: 'health-check.log'
+    });
+
+    const notificationCenter = new NotificationCenterService({
+        repoRoot: resolvedRepoRoot,
+        logger
+    });
+
+    const providers = createHealthCheckProviders({
+        repoRoot: resolvedRepoRoot,
+        getGitTreeState,
+        heartbeatPath: path.join('.audit_tmp', 'guard-heartbeat.json'),
+        tokenUsagePath: path.join('.audit_tmp', 'token-usage.jsonl'),
+        evidencePath: '.AI_EVIDENCE.json'
+    });
+
+    const service = new HealthCheckService({
+        repoRoot: resolvedRepoRoot,
+        providers,
+        notificationCenter,
+        logger,
+        outputFile: path.join(resolvedRepoRoot, '.audit_tmp', 'health-status.json')
+    });
+
+    try {
+        await service.collect('cli');
+    } finally {
+        notificationCenter.shutdown();
+    }
+}
+
+if (require.main === module) {
+    runHealthCheck()
+        .then(() => process.exit(0))
+        .catch(error => {
+            console.error('[health-check] Execution failed', error);
+            process.exit(1);
+        });
+}
+
+module.exports = { runHealthCheck };

package/scripts/hooks-system/infrastructure/watchdog/token-monitor-loop.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════
+# Token Monitor Loop
+# ═══════════════════════════════════════════════════════════════
+# Ejecuta el monitor de tokens en bucle para disparar alertas
+# periódicas sin intervención manual.
+# ═══════════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+SCRIPT="$REPO_ROOT/infrastructure/watchdog/token-monitor.js"
+INTERVAL=${TOKEN_MONITOR_INTERVAL:-300}
+
+trap 'exit 0' SIGINT SIGTERM
+
+while true; do
+  node "$SCRIPT" || true
+  sleep "$INTERVAL"
+done

package/scripts/hooks-system/infrastructure/watchdog/token-monitor.js

@@ -0,0 +1,69 @@
+const path = require('path');
+
+const NotificationCenterService = require('../../application/services/notification/NotificationCenterService');
+const TokenMonitorService = require('../../application/services/token/TokenMonitorService');
+const { createUnifiedLogger } = require('../logging/UnifiedLoggerFactory');
+
+async function runTokenMonitor({
+    repoRoot = null,
+    notificationCenter = null,
+    logger = null,
+    service = null
+} = {}) {
+    const envRoot = process.env.HOOKS_REPO_ROOT ? path.resolve(process.env.HOOKS_REPO_ROOT) : null;
+    const resolvedRepoRoot = repoRoot || envRoot || path.resolve(__dirname, '../..');
+
+    const resolvedNotificationCenter = notificationCenter || new NotificationCenterService({
+        repoRoot: resolvedRepoRoot,
+        enabled: true
+    });
+
+    const resolvedLogger = logger || createUnifiedLogger({
+        repoRoot: resolvedRepoRoot,
+        component: 'TokenMonitor',
+        fileName: 'token-monitor.log'
+    });
+
+    const monitorService = service || new TokenMonitorService({
+        repoRoot: resolvedRepoRoot,
+        notificationCenter: resolvedNotificationCenter,
+        logger: resolvedLogger
+    });
+
+    const metrics = await monitorService.run();
+
+    const staleTag = metrics.stale ? ' (stale)' : '';
+    resolvedLogger.info('TOKEN_MONITOR_RESULT', {
+        level: metrics.level,
+        percentUsed: metrics.percentUsed,
+        tokensUsed: metrics.tokensUsed,
+        maxTokens: metrics.maxTokens,
+        source: metrics.source,
+        stale: metrics.stale,
+        untrusted: metrics.untrusted
+    }, {
+        message: `Result level=${metrics.level} percent=${metrics.percentUsed}% used=${metrics.tokensUsed}/${metrics.maxTokens} source=${metrics.source}${staleTag}`
+    });
+
+    let exitCode = 0;
+    if (metrics.level === 'critical') {
+        exitCode = 2;
+    } else if (metrics.level === 'warning') {
+        exitCode = 1;
+    }
+
+    return { exitCode, metrics };
+}
+
+if (require.main === module) {
+    runTokenMonitor()
+        .then(({ exitCode }) => {
+            process.exit(exitCode);
+        })
+        .catch(error => {
+            console.error('[token-monitor] Execution failed', error);
+            process.exit(1);
+        });
+}
+
+module.exports = { runTokenMonitor };