hookherald 0.3.2 → 0.5.0

package/README.md

@@ -1,17 +1,15 @@
 # HookHerald
 
-A webhook relay that pushes notifications into running [Claude Code](https://claude.ai/code) sessions. Any system that can fire an HTTP POST — CI pipelines, monitoring alerts, deployment hooks, chat bots, cron jobs — can send messages directly into your Claude conversation.
+A webhook relay and watcher system that pushes notifications into running [Claude Code](https://claude.ai/code) sessions. Any system that can fire an HTTP POST — or any script that can print to stdout — can send messages directly into your Claude conversation.
 
 ## How It Works
 
 ```
-Webhook POST ──> Router (auth + route) ──> Channel ──> Claude Code session
-                   :9000                   (MCP)       <channel> notification
+Webhooks:  HTTP POST ──> Router ──> Channel ──> Claude Code
+Watchers:  Script stdout ──> Channel ──> Router ──> Channel ──> Claude Code
 ```
 
-The **router** is a central HTTP server that receives webhooks and forwards them by `project_slug` to the right session. Each Claude Code session runs a **channel** (MCP server) that auto-registers with the router. The **CLI** (`hh`) sets everything up.
-
-Payloads are forwarded as raw JSON — send whatever you want, the agent figures it out.
+The **router** is a local HTTP server that receives webhooks and forwards them by `project_slug`. Each Claude Code session runs a **channel** (MCP server) that auto-registers with the router. **Watchers** are scripts that run on an interval — their stdout becomes notifications. The **CLI** (`hh`) sets everything up.
 
 ## Install
 
@@ -31,20 +29,104 @@ hh router --bg
 cd ~/my-project
 hh init
 
-# 3. Start Claude Code
+# 3. Start Claude Code (from the same directory — it needs .mcp.json and .hookherald.json)
 claude --dangerously-load-development-channels server:webhook-channel
 
 # 4. Send a webhook
 curl -X POST http://127.0.0.1:9000/ \
   -H "Content-Type: application/json" \
-  -H "X-Webhook-Token: dev-secret" \
   -d '{"project_slug":"my-group/my-project","status":"deployed","version":"1.2.3"}'
 ```
 
+No auth by default — localhost is trusted. See [Auth](#auth) to enable it.
+
+## Watchers
+
+Watchers poll external systems and push notifications into Claude Code. Configure them in `.hookherald.json` (created by `hh init`):
+
+```json
+{
+  "slug": "mygroup/myapp",
+  "router_url": "http://127.0.0.1:9000",
+  "watchers": [
+    { "command": "./check-pipeline.sh", "interval": 30 },
+    { "command": "kubectl get pods -n default -o json", "interval": 60 }
+  ]
+}
+```
+
+The contract is simple — HookHerald runs your command and forwards whatever it prints:
+- **stdout = send** — any non-empty stdout gets forwarded to Claude Code as a notification
+- **no stdout = skip** — nothing happens, no notification
+- **exit code doesn't matter** — only stdout counts, output is captured even on non-zero exit
+- **JSON stdout is parsed** — valid JSON stays structured, plain text stays as a string
+- **No diffing** — HookHerald doesn't compare outputs between runs. If your script prints something, it gets sent. The script decides when to fire and handles its own state/dedup.
+
+### Example: Watch Kubernetes Pods
+
+```bash
+#!/bin/bash
+# watch-pods.sh — notify when pod states change
+STATE_FILE="/tmp/hh-pods-state"
+
+CURRENT=$(kubectl get pods -n default -o json 2>/dev/null | jq -c \
+  '[.items[] | {name: .metadata.name, phase: .status.phase, ready: (.status.containerStatuses // [] | map(.ready) | all), restarts: (.status.containerStatuses // [] | map(.restartCount) | add // 0)}] | sort_by(.name)')
+
+if [ -z "$CURRENT" ] || [ "$CURRENT" = "[]" ]; then exit 0; fi
+
+LAST=$(cat "$STATE_FILE" 2>/dev/null)
+if [ "$CURRENT" = "$LAST" ]; then exit 0; fi
+
+echo "$CURRENT" > "$STATE_FILE"
+echo "$CURRENT" | jq '{
+  pods: .,
+  summary: {
+    total: (. | length),
+    running: ([.[] | select(.phase == "Running")] | length),
+    not_ready: ([.[] | select(.ready == false)] | length),
+    crashing: ([.[] | select(.restarts > 3)] | length)
+  }
+}'
+```
+
+### Example: Watch GitLab Pipeline
+
+```bash
+#!/bin/bash
+# check-pipeline.sh — notify on pipeline completion
+STATE_FILE="/tmp/hh-pipeline-last"
+
+PIPELINE=$(curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "https://gitlab.com/api/v4/projects/mygroup%2Fmyapp/pipelines/latest")
+
+ID=$(echo "$PIPELINE" | jq -r '.id')
+STATUS=$(echo "$PIPELINE" | jq -r '.status')
+LAST=$(cat "$STATE_FILE" 2>/dev/null)
+
+case "$STATUS" in
+  failed|success|canceled)
+    [ "$ID" = "$LAST" ] && exit 0
+    echo "$ID" > "$STATE_FILE"
+    echo "$PIPELINE" | jq '{
+      pipeline_id: .id,
+      status: .status,
+      ref: .ref,
+      url: .web_url
+    }'
+    ;;
+esac
+```
+
+### Hot Reload
+
+Edit `.hookherald.json` while Claude Code is running — watchers are added/removed automatically. No restart needed. The dashboard updates within 30 seconds.
+
+See [examples/README.md](examples/README.md) for detailed walkthroughs, more scripts, writing your own watchers, and troubleshooting.
+
 ## CLI
 
 ```
-hh init   [--slug <slug>] [--router-url <url>]   Set up .mcp.json in current directory
+hh init   [--slug <slug>] [--router-url <url>]   Set up .mcp.json + .hookherald.json
 hh status [--router-url <url>]                    Show active sessions
 hh kill   <slug> [--router-url <url>]             Bounce a session
 hh router [--port <port>] [--secret <secret>]     Start the webhook router
@@ -52,69 +134,74 @@ hh router [--port <port>] [--secret <secret>]     Start the webhook router
 hh router stop                                    Stop background router
 ```
 
-`hh init` auto-detects the project slug from `git remote origin`. Merges with existing `.mcp.json` if present.
+`hh init` auto-detects the project slug from `git remote origin`. Creates `.hookherald.json` with an empty watchers array. Merges with existing `.mcp.json` if present. Won't overwrite an existing `.hookherald.json`.
+
+`hh kill` signals the channel to shut down. Claude Code will respawn it.
+
+## Auth
+
+Auth is opt-in. By default, no secret is needed — everything runs on localhost.
+
+```bash
+# No auth (default)
+hh router
+
+# Enable auth on webhook ingestion
+hh router --secret my-secret
+```
+
+When a secret is set, `POST /` requires `X-Webhook-Token` (or `X-Gitlab-Token`). Internal endpoints (`/register`, `/unregister`, `/api/kill`) never require auth.
 
-`hh kill` signals the channel to shut down. Claude Code will respawn it — use this to bounce a session, not permanently remove it.
+For external sources (GitLab CI, GitHub Actions), start the router with `--secret` and configure the same secret in the webhook settings.
 
 ## Docker
 
 The router can also run via Docker (requires `--network host` on Linux):
 
 ```bash
+docker run -d --network host shoofio/hookherald
+
+# With auth
 docker run -d --network host -e WEBHOOK_SECRET=my-secret shoofio/hookherald
 ```
 
 > For rootless Docker or Docker Desktop (Mac/Windows), use `hh router` instead.
 
+## Dashboard
+
+Live session management UI at `http://127.0.0.1:9000/`:
+
+- **Sessions** — status, events, errors, latency, kill button
+- **Watchers** — shown per session with command and interval, click to filter events by source
+- **Events** — click sessions to filter, ctrl/shift for multi-select, expand for trace waterfall and payload
+- **Live** — SSE-powered, no refresh needed
+
 ## Router API
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `POST` | `/` | Receive webhook (requires `X-Webhook-Token` or `X-Gitlab-Token`) |
+| `POST` | `/` | Receive webhook (auth required only if `WEBHOOK_SECRET` is set) |
 | `POST` | `/api/kill` | Remove a session (signals channel to shut down) |
-| `GET` | `/` | Session management dashboard |
+| `GET` | `/` | Dashboard |
 | `GET` | `/api/health` | Health check |
-| `GET` | `/api/sessions` | Active sessions with metrics |
+| `GET` | `/api/sessions` | Active sessions with metrics and watchers |
 | `GET` | `/api/events` | Query events (`?slug=`, `?limit=`, `?offset=`) |
 | `GET` | `/api/events/:id` | Single event by ID |
 | `GET` | `/api/stream` | SSE live updates |
 | `GET` | `/metrics` | Prometheus format |
 
-## Dashboard
-
-Live session management UI at `http://127.0.0.1:9000/`:
-
-- **Sessions** — status, events, errors, latency, kill button
-- **Events** — click sessions to filter, ctrl/shift for multi-select
-- **Detail** — trace waterfall, raw payload
-- **Live** — SSE-powered, no refresh
-
-## GitLab CI
-
-Add a webhook in project settings, or use a CI step:
-
-```yaml
-notify:
-  stage: .post
-  script:
-    - |
-      curl -s -X POST http://$ROUTER_HOST:9000/ \
-        -H "Content-Type: application/json" \
-        -H "X-Webhook-Token: $WEBHOOK_SECRET" \
-        -d "{\"project_slug\":\"$CI_PROJECT_PATH\",\"status\":\"$CI_PIPELINE_STATUS\",\"branch\":\"$CI_COMMIT_BRANCH\",\"sha\":\"$CI_COMMIT_SHA\"}"
-```
-
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `ROUTER_PORT` | `9000` | Router listen port |
 | `ROUTER_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for Docker) |
-| `WEBHOOK_SECRET` | `dev-secret` | Auth secret |
+| `WEBHOOK_SECRET` | *(none)* | Auth secret (opt-in) |
 | `PROJECT_SLUG` | `unknown/project` | Channel's project ID |
 | `ROUTER_URL` | `http://127.0.0.1:9000` | Router address |
 | `LOG_LEVEL` | `info` | debug/info/warn/error |
 | `HH_HEARTBEAT_MS` | `30000` | Channel heartbeat interval |
+| `HH_CONFIG_PATH` | *(none)* | Path to `.hookherald.json` (set by `hh init`) |
 
 ## License
 

package/bin/hh

@@ -1,2 +1,14 @@
 #!/bin/sh
-exec npx tsx "$(dirname "$(readlink -f "$0")")/../src/cli.ts" "$@"
+# Resolve symlinks to find the actual package directory
+SELF="$0"
+while [ -L "$SELF" ]; do
+  DIR="$(cd "$(dirname "$SELF")" && pwd)"
+  SELF="$(readlink "$SELF")"
+  case "$SELF" in /*) ;; *) SELF="$DIR/$SELF" ;; esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SELF")" && pwd)"
+PKG_DIR="$SCRIPT_DIR/.."
+
+# Use node --import directly instead of npx tsx for faster startup
+TSX_LOADER="$PKG_DIR/node_modules/tsx/dist/esm/index.mjs"
+exec node --import "$TSX_LOADER" "$PKG_DIR/src/cli.ts" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookherald",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Webhook relay for Claude Code — push notifications from any HTTP POST into running sessions",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -16,7 +16,6 @@ const PID_FILE = resolve(PID_DIR, "router.pid");
 
 const DEFAULT_ROUTER_URL = "http://127.0.0.1:9000";
 const DEFAULT_PORT = "9000";
-const DEFAULT_SECRET = "dev-secret";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -45,8 +44,9 @@ function detectSlug(): string {
     }).trim();
 
     // SSH: git@gitlab.com:group/project.git
+    // Skip if it looks like a URL scheme (e.g. https:)
     const lastColon = remote.lastIndexOf(":");
-    if (lastColon !== -1 && !remote.slice(0, lastColon).includes("/")) {
+    if (lastColon !== -1 && !remote.includes("://")) {
       const slug = remote.slice(lastColon + 1).replace(/\.git$/, "");
       if (slug.includes("/")) return slug;
     }
@@ -81,17 +81,33 @@ async function cmdInit() {
 
   if (!config.mcpServers) config.mcpServers = {};
 
+  const hhConfigPath = resolve(process.cwd(), ".hookherald.json");
+
   config.mcpServers["webhook-channel"] = {
     command: "node",
     args: ["--import", resolve(TSX_PATH, "dist", "esm", "index.mjs"), CHANNEL_PATH],
     env: {
       PROJECT_SLUG: slug,
       ROUTER_URL: routerUrl,
+      HH_CONFIG_PATH: hhConfigPath,
     },
   };
 
   writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
-  console.log(`Initialized HookHerald for ${slug} in .mcp.json`);
+
+  // Write .hookherald.json if it doesn't exist
+  if (!existsSync(hhConfigPath)) {
+    const hhConfig = {
+      slug,
+      router_url: routerUrl,
+      watchers: [],
+    };
+    writeFileSync(hhConfigPath, JSON.stringify(hhConfig, null, 2) + "\n");
+    console.log(`Initialized HookHerald for ${slug}`);
+    console.log(`  Config:  ${hhConfigPath}`);
+  } else {
+    console.log(`Initialized HookHerald for ${slug} (config already exists)`);
+  }
   console.log(`  Channel: ${CHANNEL_PATH}`);
   console.log(`  Router:  ${routerUrl}`);
 }
@@ -184,7 +200,7 @@ function cmdRouter() {
   }
 
   const port = getFlag("port") || process.env.ROUTER_PORT || DEFAULT_PORT;
-  const secret = getFlag("secret") || process.env.WEBHOOK_SECRET || DEFAULT_SECRET;
+  const secret = getFlag("secret") || process.env.WEBHOOK_SECRET || "";
   const bg = hasFlag("bg");
 
   const child = spawn("node", ["--import", resolve(TSX_PATH, "dist", "esm", "index.mjs"), ROUTER_PATH], {

package/src/dashboard.html

@@ -284,6 +284,28 @@
     border-radius: 4px;
   }
   .filter-bar label { color: var(--text-dim); }
+
+  /* Watcher rows */
+  .watcher-row td { padding: 0 12px 8px !important; border-bottom: 1px solid var(--border); }
+  .watcher-row.selected td { background: #1a2636; }
+  .watchers-list { display: flex; flex-wrap: wrap; gap: 6px; }
+  .watcher-tag {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    font-family: var(--mono);
+    font-size: 11px;
+    padding: 2px 8px;
+    border-radius: 3px;
+    background: #1a2a3a;
+    color: var(--text-dim);
+    border: 1px solid var(--border);
+  }
+  .watcher-tag { cursor: pointer; }
+  .watcher-tag:hover { border-color: var(--blue); }
+  .watcher-tag.active { background: #1a3a5f; border-color: var(--blue); color: var(--text); }
+  .watcher-icon { font-size: 10px; }
+  .watcher-interval { color: var(--blue); font-weight: 600; }
 </style>
 </head>
 <body>
@@ -335,6 +357,7 @@ const state = {
   expandedEventId: null,
   selectedSlugs: new Set(),
   filterType: '',
+  filterSource: '',
 };
 
 // --- SSE ---
@@ -431,6 +454,14 @@ function renderSessions() {
       <td class="last-event-cell" data-ts="${s.lastEventAt || ''}">${s.lastEventAt ? timeAgo(s.lastEventAt) : 'never'}</td>
       <td><button class="btn-kill" onclick="event.stopPropagation(); killSession('${esc(s.slug)}')">kill</button></td>
     </tr>`;
+    if (s.watchers && s.watchers.length > 0) {
+      html += `<tr class="watcher-row${sel}"><td colspan="8"><div class="watchers-list">`;
+      for (const w of s.watchers) {
+        const active = state.filterSource === w.command ? ' active' : '';
+        html += `<span class="watcher-tag${active}" title="${esc(w.command)}" onclick="event.stopPropagation(); filterBySource('${esc(w.command)}')"><span class="watcher-icon">&#9201;</span>${esc(w.command.length > 40 ? w.command.slice(0, 37) + '...' : w.command)} <span class="watcher-interval">${w.interval}s</span></span>`;
+      }
+      html += '</div></td></tr>';
+    }
   }
 
   html += '</tbody></table>';
@@ -472,22 +503,28 @@ function selectSession(slug, ev) {
   updateFilterHint();
 }
 
+function filterBySource(cmd) {
+  state.filterSource = state.filterSource === cmd ? '' : cmd;
+  renderSessions();
+  renderEvents();
+  updateFilterHint();
+}
+
 function updateFilterHint() {
   const el = document.getElementById('filterHint');
+  const parts = [];
   const n = state.selectedSlugs.size;
-  if (n === 0) {
-    el.textContent = 'Showing all sessions';
-  } else if (n === 1) {
-    el.textContent = 'Filtered: ' + [...state.selectedSlugs][0];
-  } else {
-    el.textContent = 'Filtered: ' + n + ' sessions';
-  }
+  if (n === 1) parts.push([...state.selectedSlugs][0]);
+  else if (n > 1) parts.push(n + ' sessions');
+  if (state.filterSource) parts.push('source: ' + state.filterSource);
+  el.textContent = parts.length ? 'Filtered: ' + parts.join(', ') : 'Showing all sessions';
 }
 
 function getFilteredEvents() {
   return state.events.filter(ev => {
     if (state.selectedSlugs.size > 0 && !state.selectedSlugs.has(ev.slug)) return false;
     if (state.filterType && ev.type !== state.filterType) return false;
+    if (state.filterSource && (!ev.payload || ev.payload.source !== state.filterSource)) return false;
     return true;
   });
 }

package/src/observability.ts

@@ -30,13 +30,20 @@ export interface RouterEvent {
   error?: string;
 }
 
+export interface WatcherConfig {
+  command: string;
+  interval: number;
+}
+
 export interface RouteInfo {
   port: number;
   registeredAt: string;
+  lastHeartbeatAt: number;
   lastEventAt: string | null;
   eventCount: number;
   errorCount: number;
   status: "up" | "down" | "unknown";
+  watchers: WatcherConfig[];
 }
 
 interface RouteMetrics {

package/src/webhook-channel.ts

@@ -1,16 +1,26 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "node:http";
-import { createLogger } from "./observability.js";
+import { readFileSync, watch as fsWatch, type FSWatcher } from "node:fs";
+import { execFile } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createLogger, type WatcherConfig } from "./observability.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf-8"));
+const VERSION = pkg.version;
 
 const PROJECT_SLUG = process.env.PROJECT_SLUG || "unknown/project";
 const ROUTER_URL = process.env.ROUTER_URL || "http://127.0.0.1:9000";
+const CONFIG_PATH = process.env.HH_CONFIG_PATH || "";
+const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || "";
 
 const log = createLogger(`channel:${PROJECT_SLUG}`, true); // stderr for MCP
 
 // --- MCP Server setup ---
 const mcp = new Server(
-  { name: "webhook-channel", version: "0.2.0" },
+  { name: "webhook-channel", version: VERSION },
   {
     capabilities: {
       experimental: { "claude/channel": {} },
@@ -95,7 +105,11 @@ async function register(): Promise<boolean> {
     const resp = await fetch(`${ROUTER_URL}/register`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ project_slug: PROJECT_SLUG, port: assignedPort }),
+      body: JSON.stringify({
+        project_slug: PROJECT_SLUG,
+        port: assignedPort,
+        watchers: currentWatcherConfigs,
+      }),
     });
     if (resp.ok) {
       if (!registered) log.info("registered with router", { router: ROUTER_URL });
@@ -117,20 +131,152 @@ function startHeartbeat() {
   heartbeatTimer.unref();
 }
 
+// --- Watcher system ---
+
+let currentWatcherConfigs: WatcherConfig[] = [];
+const watcherIntervals: Map<string, ReturnType<typeof setInterval>> = new Map();
+let configWatcher: FSWatcher | null = null;
+
+function readConfig(): { slug: string; router_url: string; watchers: WatcherConfig[] } | null {
+  if (!CONFIG_PATH) return null;
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function executeCommand(cmd: string): Promise<string> {
+  return new Promise((resolve) => {
+    execFile("sh", ["-c", cmd], { encoding: "utf-8", timeout: 60000 }, (err, stdout) => {
+      resolve((stdout || "").trim());
+    });
+  });
+}
+
+async function runWatcher(watcher: WatcherConfig) {
+  const output = await executeCommand(watcher.command);
+  if (!output) return;
+
+  let parsed: any;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    parsed = output;
+  }
+
+  const envelope = {
+    project_slug: PROJECT_SLUG,
+    source: watcher.command,
+    output: parsed,
+  };
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (WEBHOOK_SECRET) headers["X-Webhook-Token"] = WEBHOOK_SECRET;
+
+  try {
+    await fetch(`${ROUTER_URL}/`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(envelope),
+    });
+    log.debug("watcher sent", { command: watcher.command });
+  } catch (err: any) {
+    log.warn("watcher POST failed", { command: watcher.command, error: err.message });
+  }
+}
+
+function watcherKey(w: WatcherConfig): string {
+  return `${w.command}::${w.interval}`;
+}
+
+function startWatchers(watchers: WatcherConfig[]) {
+  // Stop removed/changed watchers
+  const newKeys = new Set(watchers.map(watcherKey));
+  for (const [key, timer] of watcherIntervals) {
+    if (!newKeys.has(key)) {
+      clearInterval(timer);
+      watcherIntervals.delete(key);
+      log.info("watcher stopped", { key });
+    }
+  }
+
+  // Start new watchers
+  for (const w of watchers) {
+    const key = watcherKey(w);
+    if (watcherIntervals.has(key)) continue;
+
+    // Run immediately (if registered), then on interval
+    if (registered) runWatcher(w);
+    const timer = setInterval(() => runWatcher(w), w.interval * 1000);
+    timer.unref();
+    watcherIntervals.set(key, timer);
+    log.info("watcher started", { command: w.command, interval: w.interval });
+  }
+
+  currentWatcherConfigs = watchers;
+}
+
+async function loadAndStartWatchers() {
+  const config = readConfig();
+  const watchers = config?.watchers || [];
+  startWatchers(watchers);
+  // Re-register so the router sees the updated watcher list
+  if (registered) await register();
+}
+
+function startConfigWatcher() {
+  if (!CONFIG_PATH) return;
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function watch() {
+    if (configWatcher) { try { configWatcher.close(); } catch {} }
+    try {
+      configWatcher = fsWatch(CONFIG_PATH, () => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          log.info("config changed, reloading watchers");
+          loadAndStartWatchers();
+          // Re-establish watcher (inode may have changed)
+          watch();
+        }, 200);
+      });
+      configWatcher.unref();
+    } catch {
+      log.debug("could not watch config file, retrying in 5s", { path: CONFIG_PATH });
+      setTimeout(watch, 5000);
+    }
+  }
+
+  watch();
+}
+
 // Bind to port 0 for auto-assignment
 httpServer.listen(0, "127.0.0.1", async () => {
   const addr = httpServer.address();
   assignedPort = typeof addr === "object" && addr ? addr.port : 0;
   log.info("HTTP server listening", { host: "127.0.0.1", port: assignedPort });
 
+  loadAndStartWatchers();
+  startConfigWatcher();
   await register();
+  // Run watchers that were deferred during startup (before registration)
+  for (const w of currentWatcherConfigs) runWatcher(w);
   startHeartbeat();
 });
 
 // Graceful shutdown: unregister from router
+let shutdownInProgress = false;
+
 async function shutdown() {
+  if (shutdownInProgress) return;
+  shutdownInProgress = true;
   log.info("shutting down");
   if (heartbeatTimer) clearInterval(heartbeatTimer);
+  for (const timer of watcherIntervals.values()) clearInterval(timer);
+  watcherIntervals.clear();
+  if (configWatcher) { configWatcher.close(); configWatcher = null; }
   try {
     await fetch(`${ROUTER_URL}/unregister`, {
       method: "POST",

package/src/webhook-router.ts

@@ -2,6 +2,7 @@ import { createServer, type IncomingMessage, type ServerResponse } from "node:ht
 import { readFileSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { timingSafeEqual } from "node:crypto";
 import {
   createLogger,
   EventStore,
@@ -15,9 +16,23 @@ import {
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+const pkg = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf-8"));
+const VERSION = pkg.version;
+
 const PORT = parseInt(process.env.ROUTER_PORT || "9000", 10);
 const HOST = process.env.ROUTER_HOST || "127.0.0.1";
-const SECRET = process.env.WEBHOOK_SECRET || "dev-secret";
+const SECRET = process.env.WEBHOOK_SECRET || "";
+
+function safeEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) {
+    // Compare against self to burn constant time, then return false
+    timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
+}
 
 const log = createLogger("router");
 const events = new EventStore();
@@ -36,9 +51,16 @@ try {
 
 // --- Request body helper ---
 
+const MAX_BODY = 10 * 1024 * 1024; // 10MB
+
 async function readBody(req: IncomingMessage): Promise<string> {
   const chunks: Buffer[] = [];
-  for await (const chunk of req) chunks.push(chunk as Buffer);
+  let size = 0;
+  for await (const chunk of req) {
+    size += (chunk as Buffer).length;
+    if (size > MAX_BODY) throw new Error("body too large");
+    chunks.push(chunk as Buffer);
+  }
   return Buffer.concat(chunks).toString();
 }
 
@@ -51,20 +73,28 @@ function getRoutesSnapshot() {
 // --- Handlers ---
 
 async function handleRegister(req: IncomingMessage, res: ServerResponse) {
-  const body = JSON.parse(await readBody(req));
-  const { project_slug, port } = body;
+  let body: any;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid JSON" }));
+    return;
+  }
+  const { project_slug, port, watchers } = body;
   if (!project_slug || !port) {
     res.writeHead(400, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "missing project_slug or port" }));
     return;
   }
 
-  // Heartbeat: if same slug already registered, treat as keepalive
+  // Heartbeat: if same slug and same port, treat as keepalive
   const existing = routes.get(project_slug);
-  if (existing) {
-    if (existing.port !== port) {
-      existing.port = port;
-      log.info("route updated", { slug: project_slug, port });
+  if (existing && existing.port === port) {
+    existing.lastHeartbeatAt = Date.now();
+    // Update watchers on heartbeat (supports hot reload)
+    if (watchers && JSON.stringify(watchers) !== JSON.stringify(existing.watchers)) {
+      existing.watchers = watchers;
       broadcast("session", { sessions: getSessionsData() });
     }
     res.writeHead(200, { "Content-Type": "application/json" });
@@ -75,10 +105,12 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
   const info: RouteInfo = {
     port,
     registeredAt: new Date().toISOString(),
+    lastHeartbeatAt: Date.now(),
     lastEventAt: null,
     eventCount: 0,
     errorCount: 0,
     status: "unknown",
+    watchers: watchers || [],
   };
   routes.set(project_slug, info);
   metrics.registrations++;
@@ -103,7 +135,14 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
 }
 
 async function handleUnregister(req: IncomingMessage, res: ServerResponse) {
-  const body = JSON.parse(await readBody(req));
+  let body: any;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid JSON" }));
+    return;
+  }
   const { project_slug } = body;
   if (!project_slug) {
     res.writeHead(400, { "Content-Type": "application/json" });
@@ -141,32 +180,34 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
   const trace = createTrace();
   const traceId = newEventId();
 
-  // Auth
+  // Auth (opt-in: only check if SECRET is configured)
   const authSpan = trace.span("auth_validate");
-  const token = req.headers["x-webhook-token"] || req.headers["x-gitlab-token"];
-  if (token !== SECRET) {
-    trace.end(authSpan);
-    log.warn("rejected: invalid token", { traceId });
-    metrics.recordRequest(401);
-    metrics.recordWebhook("unauthorized");
-
-    const ev: RouterEvent = {
-      id: traceId,
-      timestamp: new Date().toISOString(),
-      type: "webhook",
-      slug: "unknown",
-      routingDecision: "unauthorized",
-      durationMs: trace.elapsed(),
-      responseStatus: 401,
-      traceSpans: trace.spans,
-      error: "invalid token",
-    };
-    events.push(ev);
-    broadcast("webhook", ev);
-
-    res.writeHead(401, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "unauthorized" }));
-    return;
+  if (SECRET) {
+    const token = req.headers["x-webhook-token"] || req.headers["x-gitlab-token"];
+    if (!safeEqual(String(token ?? ""), SECRET)) {
+      trace.end(authSpan);
+      log.warn("rejected: invalid token", { traceId });
+      metrics.recordRequest(401);
+      metrics.recordWebhook("unauthorized");
+
+      const ev: RouterEvent = {
+        id: traceId,
+        timestamp: new Date().toISOString(),
+        type: "webhook",
+        slug: "unknown",
+        routingDecision: "unauthorized",
+        durationMs: trace.elapsed(),
+        responseStatus: 401,
+        traceSpans: trace.spans,
+        error: "invalid token",
+      };
+      events.push(ev);
+      broadcast("webhook", ev);
+
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "unauthorized" }));
+      return;
+    }
   }
   trace.end(authSpan);
 
@@ -294,6 +335,7 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     };
     events.push(ev);
     broadcast("webhook", ev);
+    broadcast("session", { sessions: getSessionsData() });
 
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ ok: true, forwarded_to: routeInfo.port }));
@@ -323,6 +365,7 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     };
     events.push(ev);
     broadcast("webhook", ev);
+    broadcast("session", { sessions: getSessionsData() });
 
     res.writeHead(502, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "downstream unreachable" }));
@@ -400,18 +443,53 @@ const statsInterval = setInterval(() => {
 }, 5000);
 statsInterval.unref();
 
+// Stale route cleanup: remove routes that missed 3 heartbeat intervals
+const HEARTBEAT_MS = parseInt(process.env.HH_HEARTBEAT_MS || "30000", 10);
+const STALE_THRESHOLD_MS = HEARTBEAT_MS * 3;
+
+const staleInterval = setInterval(() => {
+  const now = Date.now();
+  let changed = false;
+  for (const [slug, info] of routes) {
+    if (now - info.lastHeartbeatAt > STALE_THRESHOLD_MS) {
+      routes.delete(slug);
+      metrics.unregistrations++;
+      log.warn("reaped stale route", { slug, lastHeartbeatAgoMs: now - info.lastHeartbeatAt });
+      events.push({
+        id: newEventId(),
+        timestamp: new Date().toISOString(),
+        type: "unregister",
+        slug,
+        routingDecision: null,
+        durationMs: 0,
+        responseStatus: 200,
+      });
+      changed = true;
+    }
+  }
+  if (changed) broadcast("session", { sessions: getSessionsData() });
+}, STALE_THRESHOLD_MS);
+staleInterval.unref();
+
 function handleApiHealth(_req: IncomingMessage, res: ServerResponse) {
   res.writeHead(200, { "Content-Type": "application/json" });
   res.end(JSON.stringify({
     status: "ok",
-    version: "0.2.0",
+    version: VERSION,
     uptimeSeconds: Math.floor((Date.now() - metrics.startTime) / 1000),
     routesActive: routes.size,
   }));
 }
 
 async function handleApiKill(req: IncomingMessage, res: ServerResponse) {
-  const body = JSON.parse(await readBody(req));
+  let body: any;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid JSON" }));
+    return;
+  }
   const { project_slug } = body;
   if (!project_slug) {
     res.writeHead(400, { "Content-Type": "application/json" });
@@ -468,6 +546,7 @@ function getSessionsData() {
       avgLatencyMs: rm?.avgLatencyMs ?? 0,
       successCount: rm?.success ?? 0,
       failedCount: rm?.failed ?? 0,
+      watchers: info.watchers,
     };
   });
 }
@@ -530,6 +609,11 @@ const server = createServer(async (req, res) => {
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "not found" }));
   } catch (err: any) {
+    if (err.message === "body too large") {
+      res.writeHead(413, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "payload too large" }));
+      return;
+    }
     log.error("unhandled error", { error: err.message, path: url.pathname });
     metrics.recordRequest(500);
     res.writeHead(500, { "Content-Type": "application/json" });
@@ -541,7 +625,8 @@ server.listen(PORT, HOST, () => {
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : PORT;
   log.info("listening", { host: HOST, port: actualPort });
-  log.info("secret", { preview: SECRET.slice(0, 4) + "..." });
+  if (SECRET) log.info("auth enabled", { preview: SECRET.slice(0, 4) + "..." });
+  else log.info("auth disabled (no WEBHOOK_SECRET set)");
   // Machine-readable line for process spawners to discover the port
   process.stderr.write(`HOOKHERALD_PORT=${actualPort}\n`);
 });