agentxchain 2.155.23 → 2.155.25

package/README.md

@@ -205,7 +205,7 @@ Partial coordinator artifacts are first-class here too: `audit` and `report` kee
 | `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |
 | `intake record\|triage\|approve\|plan\|start\|scan\|resolve` | Continuous-delivery intake: turn delivery signals into governed work items |
 | `intake handoff` | Bridge a planned intake intent to a coordinator workstream for multi-repo execution |
-| `watch --event-file\|--event-dir\|--results\|--result` | Normalize external events into governed intake, poll event-file directories, and inspect durable watch result records |
+| `watch --event-file\|--event-dir\|--listen\|--results\|--result` | Normalize external events into governed intake, poll event-file directories, receive signed HTTP webhooks, and inspect durable watch result records |
 | `schedule list\|run-due\|daemon\|status` | Run repo-local lights-out scheduling: inspect schedules, execute due runs, poll in a local daemon loop, continue explicitly unblocked schedule-owned runs, or check daemon heartbeat |
 | `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins under `.agentxchain/plugins/` |
 | `plugin list-available` | List bundled built-in plugins installable by short name |

package/bin/agentxchain.js

@@ -254,6 +254,10 @@ program
   .option('--event-dir <path>', 'Poll a directory for external event JSON files')
   .option('--poll-seconds <seconds>', 'With --event-dir, polling interval in seconds', '5')
   .option('--dry-run', 'With --event-file, print the normalized intake payload without writing')
+  .option('--listen <port>', 'Start an HTTP webhook listener on the given port')
+  .option('--listen-host <host>', 'With --listen, bind to a specific host (default: 127.0.0.1)')
+  .option('--webhook-secret <secret>', 'With --listen, HMAC-SHA256 secret for signature verification')
+  .option('--allow-unsigned', 'With --listen, accept unsigned payloads (local dev only)')
   .option('--results', 'List all watch result records')
   .option('--result <id>', 'Show a single watch result by ID or filename')
   .option('--limit <n>', 'With --results, limit the number of results shown')

package/dashboard/app.js

@@ -21,6 +21,7 @@ import { render as renderChain } from './components/chain.js';
 import { render as renderRunHistory } from './components/run-history.js';
 import { render as renderTimeouts } from './components/timeouts.js';
 import { render as renderCoordinatorTimeouts } from './components/coordinator-timeouts.js';
+import { render as renderWatch } from './components/watch.js';
 import {
   buildLiveMeta,
   createLiveEventFromMessage,
@@ -42,6 +43,7 @@ const VIEWS = {
   mission: { fetch: ['missions', 'plans'], render: renderMission },
   chain: { fetch: ['chainReports'], render: renderChain },
   'run-history': { fetch: ['runHistory'], render: renderRunHistory },
+  watch: { fetch: ['watchResults'], render: renderWatch },
   timeouts: { fetch: ['timeouts'], render: renderTimeouts },
   'coordinator-timeouts': { fetch: ['coordinatorTimeouts'], render: renderCoordinatorTimeouts },
 };
@@ -70,6 +72,7 @@ const API_MAP = {
   chainReports: '/api/chain-reports',
   connectors: '/api/connectors',
   runHistory: '/api/run-history',
+  watchResults: '/api/watch-results',
   timeouts: '/api/timeouts',
   coordinatorTimeouts: '/api/coordinator/timeouts',
   gateActions: '/api/gate-actions',

package/dashboard/components/watch.js

@@ -0,0 +1,131 @@
+function esc(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function classify(record) {
+  if (Array.isArray(record?.errors) && record.errors.length > 0) return 'error';
+  if (record?.deduplicated === true) return 'deduplicated';
+  if (record?.route?.started === true) return 'started';
+  if (record?.route?.planned === true) return 'planned';
+  if (record?.route?.approved === true) return 'approved';
+  if (record?.route?.triaged === true) return 'triaged';
+  if (record?.route?.matched === false) return 'unrouted';
+  return 'detected';
+}
+
+function statusBadge(record) {
+  const status = classify(record);
+  const colors = {
+    error: 'var(--red)',
+    deduplicated: 'var(--yellow)',
+    started: 'var(--green)',
+    planned: 'var(--accent)',
+    approved: 'var(--accent)',
+    triaged: 'var(--text)',
+    unrouted: 'var(--text-dim)',
+    detected: 'var(--text-dim)',
+  };
+  return badge(status, colors[status] || 'var(--text-dim)');
+}
+
+function formatTime(value) {
+  if (!value) return '—';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString();
+}
+
+function renderResultRow(record) {
+  const payload = record.payload || {};
+  const route = record.route || {};
+  const errors = Array.isArray(record.errors) ? record.errors : [];
+  const routeDetail = route.matched === false
+    ? 'No route'
+    : [
+        route.run_id ? `run ${route.run_id}` : null,
+        route.role ? `role ${route.role}` : null,
+        route.preferred_role ? `hint ${route.preferred_role}` : null,
+      ].filter(Boolean).join(' · ') || 'Route matched';
+
+  return `<tr${errors.length > 0 ? ' style="border-left:3px solid var(--red)"' : ''}>
+    <td>
+      <div class="mono">${esc(record.result_id || '—')}</div>
+      <div class="turn-status">${esc(formatTime(record.timestamp))}</div>
+    </td>
+    <td>${statusBadge(record)}</td>
+    <td>
+      <div class="mono">${esc(payload.category || 'unknown')}</div>
+      <div class="turn-status">${esc(payload.repo || '—')}${payload.ref ? ` · ${esc(payload.ref)}` : ''}</div>
+    </td>
+    <td>
+      <div>${esc(routeDetail)}</div>
+      <div class="turn-status">Intent ${esc(record.intent_id || '—')} · Event ${esc(record.event_id || '—')}</div>
+    </td>
+    <td class="mono">${esc(record.delivery_id || '—')}</td>
+    <td>${errors.length > 0 ? esc(errors.join(' | ')) : '—'}</td>
+  </tr>`;
+}
+
+export function render({ watchResults }) {
+  if (!watchResults) {
+    return `<div class="placeholder"><h2>Watch</h2><p>No watch result data available.</p></div>`;
+  }
+
+  if (watchResults.ok === false) {
+    return `<div class="placeholder"><h2>Watch</h2><p>${esc(watchResults.error || 'Failed to load watch results.')}</p></div>`;
+  }
+
+  const recent = Array.isArray(watchResults.recent) ? watchResults.recent : [];
+  const summary = watchResults.summary || {};
+  const byStatus = summary.by_status || {};
+
+  if ((watchResults.total || 0) === 0 && (watchResults.corrupt || 0) === 0) {
+    return `<div class="placeholder"><h2>Watch</h2><p>No watch intake results yet. Use <code>agentxchain watch --listen</code>, <code>--event-file</code>, or <code>--event-dir</code> to ingest events.</p></div>`;
+  }
+
+  let html = `<div class="watch-view"><div class="run-header"><div class="run-meta">`;
+  html += badge(`${watchResults.total || 0} results`, 'var(--accent)');
+  html += badge(`${summary.routed || 0} routed`, 'var(--green)');
+  html += badge(`${summary.unrouted || 0} unrouted`, summary.unrouted ? 'var(--yellow)' : 'var(--text-dim)');
+  html += badge(`${summary.deduplicated || 0} deduped`, summary.deduplicated ? 'var(--yellow)' : 'var(--text-dim)');
+  html += badge(`${summary.errored || 0} errors`, summary.errored ? 'var(--red)' : 'var(--text-dim)');
+  if (watchResults.corrupt) html += badge(`${watchResults.corrupt} corrupt`, 'var(--red)');
+  html += `</div></div>`;
+
+  html += `<div class="section"><h3>Intake Summary</h3>
+    <p class="section-subtitle">Last result: ${esc(formatTime(summary.last_timestamp))}</p>
+    <table class="data-table">
+      <thead><tr><th>Status</th><th>Count</th></tr></thead>
+      <tbody>${Object.keys(byStatus).sort().map((status) => `<tr><td>${esc(status)}</td><td>${esc(byStatus[status])}</td></tr>`).join('')}</tbody>
+    </table>
+  </div>`;
+
+  html += `<div class="section"><h3>Recent Watch Results</h3>
+    <table class="data-table">
+      <thead>
+        <tr>
+          <th>Result</th>
+          <th>Status</th>
+          <th>Payload</th>
+          <th>Route</th>
+          <th>Delivery</th>
+          <th>Errors</th>
+        </tr>
+      </thead>
+      <tbody>${recent.map(renderResultRow).join('')}</tbody>
+    </table>
+  </div>`;
+
+  html += `</div>`;
+  return html;
+}

package/dashboard/index.html

@@ -409,6 +409,7 @@
     <a href="#mission">Mission</a>
     <a href="#chain">Chain</a>
     <a href="#run-history">Run History</a>
+    <a href="#watch">Watch</a>
     <a href="#timeouts">Timeouts</a>
     <a href="#coordinator-timeouts">Coordinator Timeouts</a>
   </nav>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.155.23",
+  "version": "2.155.25",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/watch.js

@@ -11,6 +11,7 @@ import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { validateProject } from '../lib/validation.js';
 import { resolveNextAgent, resolveExpectedClaimer } from '../lib/next-owner.js';
 import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
+import { startWebhookListener } from '../lib/watch-listener.js';
 
 const PID_FILE = '.agentxchain-watch.pid';
 
@@ -20,6 +21,11 @@ export async function watchCommand(opts) {
     return;
   }
 
+  if (opts.listen) {
+    await listenWebhook(opts);
+    return;
+  }
+
   if (opts.eventFile) {
     await ingestWatchEvent(opts);
     return;
@@ -311,6 +317,99 @@ function parsePollMs(value) {
   return Math.max(100, Math.round(seconds * 1000));
 }
 
+async function listenWebhook(opts) {
+  // Mutual exclusion checks
+  const incompatible = [
+    opts.eventFile && '--event-file',
+    opts.eventDir && '--event-dir',
+    opts.daemon && '--daemon',
+    (opts.results || opts.result) && '--results/--result',
+  ].filter(Boolean);
+
+  if (incompatible.length > 0) {
+    const message = `--listen cannot be combined with ${incompatible.join(', ')}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  const root = requireIntakeWorkspaceOrExit(opts);
+  const port = parseInt(opts.listen, 10);
+  if (!Number.isFinite(port) || port < 1 || port > 65535) {
+    const message = `invalid port: ${opts.listen}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  // Resolve webhook secret: CLI flag > env var > config
+  let secret = opts.webhookSecret || null;
+  if (!secret && process.env.AGENTXCHAIN_WEBHOOK_SECRET) {
+    secret = process.env.AGENTXCHAIN_WEBHOOK_SECRET;
+  }
+  if (!secret) {
+    try {
+      const rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+      secret = rawConfig?.watch?.webhook_secret || null;
+    } catch {}
+  }
+
+  const allowUnsigned = opts.allowUnsigned === true;
+  const host = opts.listenHost || '127.0.0.1';
+
+  try {
+    const server = await startWebhookListener({
+      root,
+      port,
+      host,
+      secret,
+      allowUnsigned,
+      dryRun: opts.dryRun === true,
+      onReady: ({ port: boundPort, host: boundHost }) => {
+        writePidFile(root);
+        console.log('');
+        console.log(chalk.bold('  AgentXchain Webhook Listener'));
+        console.log(chalk.dim(`  Listening: http://${boundHost}:${boundPort}`));
+        console.log(chalk.dim(`  Webhook:   POST /webhook`));
+        console.log(chalk.dim(`  Health:    GET  /health`));
+        console.log(chalk.dim(`  Secret:    ${secret ? 'configured' : allowUnsigned ? 'none (unsigned allowed)' : 'REQUIRED but missing — POST /webhook will return 403'}`));
+        if (opts.dryRun) console.log(chalk.yellow('  Dry-run:   events will NOT be persisted'));
+        console.log('');
+        console.log(chalk.cyan('  Waiting for webhook deliveries... (Ctrl+C to stop)'));
+        console.log('');
+      },
+    });
+
+    const cleanup = () => {
+      server.close();
+      removePidFile(root);
+      console.log('');
+      log('stop', 'Webhook listener stopped.');
+      process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      const message = `port ${port} is already in use`;
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+      } else {
+        console.log(chalk.red(`  ${message}`));
+      }
+    } else {
+      console.log(chalk.red(`  failed to start listener: ${err.message}`));
+    }
+    process.exit(1);
+  }
+}
+
 async function ingestWatchEvent(opts) {
   if (opts.daemon) {
     const message = '--daemon cannot be combined with --event-file';

package/src/lib/dashboard/bridge-server.js

@@ -33,6 +33,7 @@ import { readGateActionSnapshot } from './gate-action-reader.js';
 import { readChainReportSnapshot } from './chain-report-reader.js';
 import { readMissionSnapshot } from './mission-reader.js';
 import { readPlanSnapshot } from './plan-reader.js';
+import { readWatchResultsSnapshot } from './watch-results-reader.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -504,6 +505,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/watch-results') {
+      const limit = url.searchParams.get('limit') ?? undefined;
+      writeJson(res, 200, readWatchResultsSnapshot(workspacePath, { limit }));
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/file-watcher.js

@@ -47,6 +47,10 @@ export class FileWatcher extends EventEmitter {
           if (!relativeDir && fileSegment === 'multirepo') {
             this.#watchPath('multirepo');
           }
+          if (!relativeDir && fileSegment === 'watch-results') {
+            this.#watchPath('watch-results');
+            this.emit('invalidate', { resource: '/api/watch-results' });
+          }
           return;
         }
 

package/src/lib/dashboard/state-reader.js

@@ -66,6 +66,7 @@ export const WATCH_DIRECTORIES = [
   MULTIREPO_DIR,
   'missions',
   'reports',
+  'watch-results',
 ];
 
 /**
@@ -94,6 +95,9 @@ export function resourcesForRelativePath(filePath) {
   if (normalized.startsWith('reports/chain-') && normalized.endsWith('.json')) {
     return ['/api/chain-reports', '/api/missions'];
   }
+  if (normalized === 'watch-results' || (normalized.startsWith('watch-results/') && normalized.endsWith('.json'))) {
+    return ['/api/watch-results'];
+  }
   return FILE_TO_RESOURCE[normalized] ? [FILE_TO_RESOURCE[normalized]] : [];
 }
 

package/src/lib/dashboard/watch-results-reader.js

@@ -0,0 +1,86 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_LIMIT = 25;
+
+export function readWatchResultsSnapshot(workspacePath, { limit = DEFAULT_LIMIT } = {}) {
+  const resultsDir = join(workspacePath, '.agentxchain', 'watch-results');
+  const parsedLimit = parseLimit(limit);
+  const records = [];
+  let corrupt = 0;
+
+  if (existsSync(resultsDir)) {
+    const entries = readdirSync(resultsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'));
+
+    for (const entry of entries) {
+      try {
+        const record = JSON.parse(readFileSync(join(resultsDir, entry.name), 'utf8'));
+        if (!record || typeof record !== 'object' || Array.isArray(record)) {
+          corrupt += 1;
+          continue;
+        }
+        records.push(record);
+      } catch {
+        corrupt += 1;
+      }
+    }
+  }
+
+  records.sort((a, b) => String(b.timestamp || '').localeCompare(String(a.timestamp || '')));
+  const recent = parsedLimit === 0 ? records : records.slice(0, parsedLimit);
+
+  return {
+    ok: true,
+    total: records.length,
+    corrupt,
+    recent,
+    summary: summarize(records, corrupt),
+  };
+}
+
+function parseLimit(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_LIMIT;
+  return parsed;
+}
+
+function summarize(records, corrupt) {
+  const byStatus = {};
+  let errored = 0;
+  let deduplicated = 0;
+  let routed = 0;
+  let unrouted = 0;
+  let lastTimestamp = null;
+
+  for (const record of records) {
+    const status = classifyWatchResult(record);
+    byStatus[status] = (byStatus[status] || 0) + 1;
+    if (status === 'error') errored += 1;
+    if (record.deduplicated === true) deduplicated += 1;
+    if (record.route?.matched === false) unrouted += 1;
+    else if (record.route?.matched === true) routed += 1;
+    if (!lastTimestamp && record.timestamp) lastTimestamp = record.timestamp;
+  }
+
+  return {
+    by_status: byStatus,
+    errored,
+    deduplicated,
+    routed,
+    unrouted,
+    corrupt,
+    last_timestamp: lastTimestamp,
+  };
+}
+
+export function classifyWatchResult(record) {
+  if (Array.isArray(record?.errors) && record.errors.length > 0) return 'error';
+  if (record?.deduplicated === true) return 'deduplicated';
+  if (record?.route?.started === true) return 'started';
+  if (record?.route?.planned === true) return 'planned';
+  if (record?.route?.approved === true) return 'approved';
+  if (record?.route?.triaged === true) return 'triaged';
+  if (record?.route?.matched === false) return 'unrouted';
+  return 'detected';
+}

package/src/lib/watch-events.js

@@ -253,7 +253,7 @@ export function resolveWatchRoute(payload, routes) {
  * @param {object} payload - the normalized watch event payload
  * @returns {{ result_id: string, result_path: string }}
  */
-export function writeWatchResult(root, pipelineResult, payload) {
+export function writeWatchResult(root, pipelineResult, payload, metadata = {}) {
   const ts = Date.now();
   const suffix = Math.random().toString(16).slice(2, 10);
   const resultId = `wr_${ts}_${suffix}`;
@@ -271,6 +271,7 @@ export function writeWatchResult(root, pipelineResult, payload) {
     intent_id: pipelineResult.intent?.intent_id || null,
     intent_status: pipelineResult.intent?.status || null,
     deduplicated: pipelineResult.deduplicated === true,
+    delivery_id: metadata.delivery_id || null,
     payload: {
       source: payload.source,
       category: payload.category,

package/src/lib/watch-listener.js

@@ -0,0 +1,297 @@
+import { createServer } from 'http';
+import { createHmac, timingSafeEqual } from 'crypto';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { recordEvent, triageIntent, approveIntent, planIntent, startIntent } from './intake.js';
+import { normalizeWatchEvent, resolveWatchRoute, writeWatchResult } from './watch-events.js';
+
+const MAX_BODY_BYTES = 1_048_576; // 1 MB
+
+/**
+ * Start an HTTP webhook listener that feeds events through the governed intake pipeline.
+ *
+ * @param {object} opts
+ * @param {string} opts.root - project root
+ * @param {number} opts.port - port to bind
+ * @param {string} [opts.host='127.0.0.1'] - host to bind
+ * @param {string|null} [opts.secret=null] - HMAC-SHA256 webhook secret
+ * @param {boolean} [opts.allowUnsigned=false] - accept unsigned payloads
+ * @param {boolean} [opts.dryRun=false] - normalize only, do not persist
+ * @param {Function} [opts.onReady] - called with { port, host } when listening
+ * @returns {Promise<import('http').Server>}
+ */
+export function startWebhookListener(opts) {
+  const { root, port, host = '127.0.0.1', secret = null, allowUnsigned = false, dryRun = false, onReady } = opts;
+  const startedAt = Date.now();
+  let eventsProcessed = 0;
+
+  let version = 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'node_modules', 'agentxchain', 'package.json'), 'utf8'));
+    version = pkg.version;
+  } catch {
+    try {
+      // Fallback: try the CLI's own package.json
+      const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+      version = pkg.version;
+    } catch {}
+  }
+
+  const server = createServer(async (req, res) => {
+    try {
+      // Health endpoint
+      if (req.method === 'GET' && req.url === '/health') {
+        writeJson(res, 200, {
+          ok: true,
+          version,
+          uptime_ms: Date.now() - startedAt,
+          events_processed: eventsProcessed,
+        });
+        return;
+      }
+
+      // Webhook endpoint
+      if (req.method === 'POST' && req.url === '/webhook') {
+        const outcome = await handleWebhook(req, res, { root, secret, allowUnsigned, dryRun, startedAt });
+        if (outcome?.counted) eventsProcessed++;
+        return;
+      }
+
+      // Method not allowed on known paths
+      if (req.url === '/webhook' || req.url === '/health') {
+        writeJson(res, 405, { ok: false, error: 'method not allowed' });
+        return;
+      }
+
+      // Not found
+      writeJson(res, 404, { ok: false, error: 'not found' });
+    } catch (err) {
+      writeJson(res, 500, { ok: false, error: 'internal error' });
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, host, () => {
+      server.removeListener('error', reject);
+      if (onReady) onReady({ port, host });
+      resolve(server);
+    });
+  });
+}
+
+async function handleWebhook(req, res, ctx) {
+  const { root, secret, allowUnsigned, dryRun } = ctx;
+
+  // Content-Type check
+  const contentType = req.headers['content-type'] || '';
+  if (!contentType.includes('application/json')) {
+    writeJson(res, 415, { ok: false, error: 'content type must be application/json' });
+    return { counted: false };
+  }
+
+  // Read body with size limit
+  let rawBody;
+  try {
+    rawBody = await readBody(req, MAX_BODY_BYTES);
+  } catch (err) {
+    if (err.message === 'payload too large') {
+      writeJson(res, 413, { ok: false, error: 'payload too large' });
+      return { counted: false };
+    }
+    writeJson(res, 400, { ok: false, error: err.message });
+    return { counted: false };
+  }
+
+  // Signature verification
+  if (secret) {
+    const sigHeader = req.headers['x-hub-signature-256'];
+    if (!sigHeader) {
+      writeJson(res, 401, { ok: false, error: 'signature verification failed' });
+      return { counted: false };
+    }
+    const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+    if (!constantTimeEqual(expected, sigHeader)) {
+      writeJson(res, 401, { ok: false, error: 'signature verification failed' });
+      return { counted: false };
+    }
+  } else if (!allowUnsigned) {
+    writeJson(res, 403, { ok: false, error: 'webhook secret required' });
+    return { counted: false };
+  }
+
+  // Parse JSON
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    writeJson(res, 400, { ok: false, error: 'invalid JSON' });
+    return { counted: false };
+  }
+
+  // Construct envelope using X-GitHub-Event header if present
+  const githubEvent = req.headers['x-github-event'];
+  const deliveryId = req.headers['x-github-delivery'] || null;
+  let envelope;
+  if (parsed.provider && parsed.event) {
+    // Already enveloped
+    envelope = parsed;
+  } else if (githubEvent) {
+    envelope = { provider: 'github', event: githubEvent, ...parsed };
+  } else {
+    envelope = parsed;
+  }
+
+  // Normalize
+  let payload;
+  try {
+    payload = normalizeWatchEvent(envelope);
+  } catch (err) {
+    writeJson(res, 422, { ok: false, error: err.message });
+    return { counted: false };
+  }
+
+  // Dry-run: return normalized payload without persisting
+  if (dryRun) {
+    writeJson(res, 200, { ok: true, dry_run: true, payload });
+    return { counted: true };
+  }
+
+  // Record event through the governed intake pipeline
+  const result = recordEvent(root, payload);
+  if (!result.ok) {
+    writeJson(res, 422, { ok: false, error: result.error || 'event recording failed' });
+    return { counted: false };
+  }
+
+  // Route-based auto-triage and auto-approve (same logic as ingestWatchEvent)
+  let routed = null;
+  if (!result.deduplicated && result.intent) {
+    let routes;
+    try {
+      const rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+      routes = rawConfig?.watch?.routes;
+    } catch {}
+
+    const resolved = resolveWatchRoute(payload, routes);
+    if (resolved) {
+      const triageFields = { ...resolved.triage };
+      if (resolved.preferred_role) triageFields.preferred_role = resolved.preferred_role;
+
+      const triageResult = triageIntent(root, result.intent.intent_id, triageFields);
+      if (triageResult.ok) {
+        result.intent = triageResult.intent;
+        routed = { triaged: true, approved: false, preferred_role: resolved.preferred_role };
+
+        if (resolved.auto_approve) {
+          const approveResult = approveIntent(root, result.intent.intent_id, {
+            approver: 'watch_route',
+            reason: `auto-approved by watch route matching ${payload.category}`,
+          });
+          if (approveResult.ok) {
+            result.intent = approveResult.intent;
+            routed.approved = true;
+
+            if (resolved.auto_start) {
+              const planResult = planIntent(root, result.intent.intent_id, {
+                force: resolved.overwrite_planning_artifacts === true,
+              });
+              if (planResult.ok) {
+                result.intent = planResult.intent;
+                routed.planned = true;
+                const startResult = startIntent(root, result.intent.intent_id, {});
+                if (startResult.ok) {
+                  result.intent = startResult.intent;
+                  routed.started = true;
+                  routed.run_id = startResult.run_id || null;
+                  routed.role = startResult.role || null;
+                } else {
+                  routed.started = false;
+                  routed.auto_start_error = startResult.error;
+                }
+              } else {
+                routed.planned = false;
+                routed.started = false;
+                routed.auto_start_error = planResult.error;
+              }
+            }
+          }
+        } else if (resolved.auto_start) {
+          routed.auto_start_skipped = 'requires auto_approve';
+        }
+      }
+    }
+  }
+
+  if (routed) result.routed = routed;
+
+  // Write durable watch result
+  const watchResult = writeWatchResult(root, result, payload, { delivery_id: deliveryId });
+
+  // Build response
+  const response = {
+    ok: true,
+    result_id: watchResult.result_id,
+    event_id: result.event?.event_id || null,
+    intent_id: result.intent?.intent_id || null,
+    intent_status: result.intent?.status || null,
+    deduplicated: result.deduplicated === true,
+    delivery_id: deliveryId,
+    route: routed
+      ? {
+          matched: true,
+          triaged: routed.triaged === true,
+          approved: routed.approved === true,
+          planned: routed.planned === true,
+          started: routed.started === true,
+          preferred_role: routed.preferred_role || null,
+          run_id: routed.run_id || null,
+          role: routed.role || null,
+        }
+      : { matched: false },
+  };
+
+  writeJson(res, 200, response);
+  return { counted: true };
+}
+
+function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let rejected = false;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > maxBytes && !rejected) {
+        rejected = true;
+        reject(new Error('payload too large'));
+        // Resume to drain remaining data so the response can be sent
+        req.resume();
+        return;
+      }
+      if (!rejected) chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!rejected) resolve(Buffer.concat(chunks));
+    });
+    req.on('error', (err) => {
+      if (!rejected) reject(err);
+    });
+  });
+}
+
+function constantTimeEqual(a, b) {
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+function writeJson(res, statusCode, payload) {
+  if (res.writableEnded) return;
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-cache',
+  });
+  res.end(JSON.stringify(payload));
+}