feat: governance & safety — anomaly persistence, auto-suspension, escalation, trust boost

Anomaly detection:
- New anomaly_events table to persist detection results
- Auto-suspend agents on high-severity anomalies (rapid bidding, rating manipulation)
- suspendAgent()/unsuspendAgent() with audit trail and SSE notification

Admin endpoints:
- GET /admin/anomalies — list anomaly events with filters
- GET /admin/agents/:id/risk — aggregate risk profile
- POST /admin/agents/:id/unsuspend — lift suspension

Auth guard:
- Specific 403 message for suspended agents
- getAgentStatus() replaces isAgentActive() for richer status handling

Human escalation:
- Disputes >$100 or repeated tribunal failures auto-escalate
- Webhook + email (via Resend) notification service
- Escalation env vars: ESCALATION_WEBHOOK_URL, ESCALATION_EMAIL, RESEND_API_KEY

Owner verification trust boost:
- Verified owners (ownerDid set) get L1 with no tasks, L2 with 1+ task
- verify-owner endpoint now recalculates and returns trust level

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: waydelyle

.env.example

@@ -86,6 +86,14 @@ CORS_ORIGINS=http://localhost:3200
 # Admin API key for privileged operations
 ADMIN_API_KEY=
 
+# ──────────────────────────────────────────────
+# Escalation Notifications (optional)
+# Triggered for disputes >$100 or repeated tribunal failures
+# ──────────────────────────────────────────────
+# ESCALATION_WEBHOOK_URL=https://hooks.slack.com/services/...
+# ESCALATION_EMAIL=admin@swarmdock.ai
+# RESEND_API_KEY=
+
 # ──────────────────────────────────────────────
 # LLM Judge (quality verification — optional)
 # ──────────────────────────────────────────────

packages/api/src/db/schema.ts

@@ -340,6 +340,24 @@ export const agentWallets = pgTable('agent_wallets', {
   uniqueIndex('agent_wallet_unique').on(table.agentId),
 ]);
 
+// ============================================
+// ANOMALY EVENTS (governance detection results)
+// ============================================
+
+export const anomalyEvents = pgTable('anomaly_events', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  agentId: uuid('agent_id').references(() => agents.id, { onDelete: 'cascade' }).notNull(),
+  type: text('type').notNull(), // rapid_bidding, rating_manipulation, dormancy_evasion
+  severity: text('severity').notNull(), // low, medium, high
+  details: text('details').notNull(),
+  actionTaken: text('action_taken').default('none').notNull(), // none, warned, suspended
+  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+}, (table) => [
+  index('idx_anomaly_events_agent').on(table.agentId),
+  index('idx_anomaly_events_type').on(table.type),
+  index('idx_anomaly_events_severity').on(table.severity),
+]);
+
 // ============================================
 // CHALLENGES (auth challenge-response)
 // ============================================

packages/api/src/lib/notify.ts

@@ -0,0 +1,75 @@
+/**
+ * Notification service for escalated disputes and critical governance events.
+ * Supports webhook (primary) and email via Resend (optional).
+ */
+
+export interface EscalationPayload {
+  disputeId: string;
+  taskId: string;
+  amount: string;
+  reason: string;
+  raisedBy: string;
+  against: string | null;
+}
+
+/**
+ * Send escalation notification via configured channels.
+ * Fails silently — escalation persistence is handled by the caller.
+ */
+export async function sendEscalationNotification(payload: EscalationPayload): Promise<void> {
+  const webhookUrl = process.env.ESCALATION_WEBHOOK_URL;
+  const email = process.env.ESCALATION_EMAIL;
+  const resendKey = process.env.RESEND_API_KEY;
+
+  if (webhookUrl) {
+    try {
+      await fetch(webhookUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          event: 'dispute.escalated',
+          ...payload,
+          timestamp: new Date().toISOString(),
+        }),
+      });
+      console.log(`[NOTIFY] Escalation webhook sent for dispute ${payload.disputeId}`);
+    } catch (err) {
+      console.error('[NOTIFY] Escalation webhook failed:', err);
+    }
+  }
+
+  if (email && resendKey) {
+    try {
+      await fetch('https://api.resend.com/emails', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${resendKey}`,
+        },
+        body: JSON.stringify({
+          from: 'SwarmDock <noreply@swarmdock.ai>',
+          to: email,
+          subject: `[SwarmDock] Dispute escalated — $${(parseInt(payload.amount) / 1_000_000).toFixed(2)} USDC`,
+          text: [
+            `Dispute ${payload.disputeId} has been escalated for manual review.`,
+            '',
+            `Task: ${payload.taskId}`,
+            `Amount: $${(parseInt(payload.amount) / 1_000_000).toFixed(2)} USDC`,
+            `Reason: ${payload.reason}`,
+            `Raised by: ${payload.raisedBy}`,
+            `Against: ${payload.against ?? 'N/A'}`,
+            '',
+            'Review at: https://swarmdock-api.onrender.com/api/v1/admin/disputes',
+          ].join('\n'),
+        }),
+      });
+      console.log(`[NOTIFY] Escalation email sent for dispute ${payload.disputeId}`);
+    } catch (err) {
+      console.error('[NOTIFY] Escalation email failed:', err);
+    }
+  }
+
+  if (!webhookUrl && !(email && resendKey)) {
+    console.warn(`[NOTIFY] No escalation channels configured for dispute ${payload.disputeId}`);
+  }
+}

packages/api/src/middleware/auth.ts

@@ -9,12 +9,10 @@ import type { Scope, AATPayload } from '@swarmdock/shared';
 
 const AGENT_STATUS_CACHE_TTL = 60; // seconds
 
-async function isAgentActive(agentId: string): Promise<boolean> {
+async function getAgentStatus(agentId: string): Promise<string> {
   const cacheKey = `agent:status:${agentId}`;
   const cached = await redisGet(cacheKey);
-  if (cached !== null) {
-    return cached === 'active';
-  }
+  if (cached !== null) return cached;
 
   const [agent] = await db
     .select({ status: agents.status })
@@ -24,8 +22,7 @@ async function isAgentActive(agentId: string): Promise<boolean> {
 
   const status = agent?.status ?? 'unknown';
   await redisSet(cacheKey, status, AGENT_STATUS_CACHE_TTL);
-
-  return status === 'active';
+  return status;
 }
 
 export type AuthContext = {
@@ -47,9 +44,12 @@ export const authMiddleware = createMiddleware<AuthContext>(async (c, next) => {
     const payload = await verifyAAT(token);
 
     // Verify agent is still active (Redis-cached, 60s TTL)
-    const active = await isAgentActive(payload.agent_id);
-    if (!active) {
-      throw new HTTPException(403, { message: 'Agent account is suspended or deregistered' });
+    const status = await getAgentStatus(payload.agent_id);
+    if (status === 'suspended') {
+      throw new HTTPException(403, { message: 'Account suspended — contact admin for review' });
+    }
+    if (status !== 'active') {
+      throw new HTTPException(403, { message: 'Agent account is not active' });
     }
 
     c.set('agent', payload);
@@ -68,8 +68,8 @@ export const optionalAuthMiddleware = createMiddleware<AuthContext>(async (c, ne
     try {
       const token = authHeader.slice(7);
       const payload = await verifyAAT(token);
-      const active = await isAgentActive(payload.agent_id);
-      if (active) {
+      const status = await getAgentStatus(payload.agent_id);
+      if (status === 'active') {
         c.set('agent', payload);
       }
     } catch {

packages/api/src/routes/admin.ts

@@ -1,6 +1,6 @@
 import { Hono } from 'hono';
 import { db } from '../db/client.js';
-import { agents, tasks, escrowTransactions, transactions, agentRatings, disputes } from '../db/schema.js';
+import { agents, tasks, escrowTransactions, transactions, agentRatings, disputes, anomalyEvents, agentReputation } from '../db/schema.js';
 import { eq, sql, count, desc, and } from 'drizzle-orm';
 import { createMiddleware } from 'hono/factory';
 import { HTTPException } from 'hono/http-exception';
@@ -16,6 +16,7 @@ import {
 } from '@swarmdock/shared';
 import { releaseEscrow, refundEscrow } from '../services/escrow.js';
 import { selectTribunalJudges } from '../services/tribunal.js';
+import { unsuspendAgent } from '../services/anomaly.js';
 import { eventBus } from '../lib/events.js';
 
 const adminAuth = createMiddleware(async (c, next) => {
@@ -262,4 +263,88 @@ app.post('/disputes/:id/resolve', adminAuth, async (c) => {
   });
 });
 
+// GET /api/v1/admin/anomalies — List anomaly events
+app.get('/anomalies', adminAuth, async (c) => {
+  const type = c.req.query('type');
+  const severity = c.req.query('severity');
+  const agentId = c.req.query('agentId');
+  const limit = Math.max(1, Math.min(parseInt(c.req.query('limit') ?? '50', 10) || 50, 200));
+  const offset = Math.max(0, parseInt(c.req.query('offset') ?? '0', 10) || 0);
+
+  const conditions = [];
+  if (type) conditions.push(eq(anomalyEvents.type, type));
+  if (severity) conditions.push(eq(anomalyEvents.severity, severity));
+  if (agentId) conditions.push(eq(anomalyEvents.agentId, agentId));
+
+  const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
+
+  const rows = await db
+    .select()
+    .from(anomalyEvents)
+    .where(whereClause)
+    .orderBy(desc(anomalyEvents.createdAt))
+    .limit(limit)
+    .offset(offset);
+
+  const [{ total }] = await db.select({ total: count() }).from(anomalyEvents).where(whereClause);
+
+  return c.json({ anomalies: rows, limit, offset, total });
+});
+
+// GET /api/v1/admin/agents/:id/risk — Agent risk profile
+app.get('/agents/:id/risk', adminAuth, async (c) => {
+  const id = c.req.param('id');
+
+  const [agent] = await db
+    .select({ id: agents.id, displayName: agents.displayName, status: agents.status, trustLevel: agents.trustLevel })
+    .from(agents)
+    .where(eq(agents.id, id))
+    .limit(1);
+
+  if (!agent) return c.json({ error: 'Agent not found' }, 404);
+
+  const anomalies = await db
+    .select()
+    .from(anomalyEvents)
+    .where(eq(anomalyEvents.agentId, id))
+    .orderBy(desc(anomalyEvents.createdAt))
+    .limit(20);
+
+  const reputation = await db
+    .select()
+    .from(agentReputation)
+    .where(eq(agentReputation.agentId, id));
+
+  const highCount = anomalies.filter((a) => a.severity === 'high').length;
+  const mediumCount = anomalies.filter((a) => a.severity === 'medium').length;
+
+  return c.json({
+    agent: { id: agent.id, displayName: agent.displayName, status: agent.status, trustLevel: agent.trustLevel },
+    anomalySummary: { total: anomalies.length, high: highCount, medium: mediumCount },
+    recentAnomalies: anomalies,
+    reputation,
+  });
+});
+
+// POST /api/v1/admin/agents/:id/unsuspend — Lift suspension
+app.post('/agents/:id/unsuspend', adminAuth, async (c) => {
+  const id = c.req.param('id');
+
+  const [agent] = await db
+    .select({ status: agents.status })
+    .from(agents)
+    .where(eq(agents.id, id))
+    .limit(1);
+
+  if (!agent) return c.json({ error: 'Agent not found' }, 404);
+  if (agent.status !== AGENT_STATUS.SUSPENDED) {
+    return c.json({ error: 'Agent is not suspended' }, 400);
+  }
+
+  const body = await c.req.json().catch(() => ({})) as { note?: string };
+  await unsuspendAgent(id, body.note ?? 'Admin unsuspend');
+
+  return c.json({ unsuspended: true, agentId: id });
+});
+
 export default app;

packages/api/src/routes/agents.ts

@@ -23,6 +23,7 @@ import { eventBus } from '../lib/events.js';
 import { getRatingsSummary } from '../services/ratings.js';
 import { provisionAgentWallet } from '../services/wallet.js';
 import { getAgentCardById } from '../services/agent-card.js';
+import { updateTrustLevel } from '../services/reputation.js';
 import { getAgentPortfolio, createPortfolioItem, updatePortfolioItem, deletePortfolioItem } from '../services/portfolio.js';
 import { fetchOrderedRowsByIds, searchAgentsIndex } from '../services/search.js';
 
@@ -775,7 +776,10 @@ app.post('/:id/verify-owner', authMiddleware, async (c) => {
     updatedAt: new Date(),
   }).where(eq(agents.id, id));
 
-  return c.json({ verified: true, ownerDid });
+  // Recalculate trust level with owner verification boost
+  const newTrustLevel = await updateTrustLevel(id);
+
+  return c.json({ verified: true, ownerDid, trustLevel: newTrustLevel });
 });
 
 export default app;

packages/api/src/routes/tasks.ts

@@ -13,6 +13,8 @@ import {
 import { eventBus } from '../lib/events.js';
 import { releaseEscrow, refundEscrow } from '../services/escrow.js';
 import { verifyTaskOutput } from '../services/quality.js';
+import { shouldEscalate } from '../services/tribunal.js';
+import { sendEscalationNotification } from '../lib/notify.js';
 import { safeAppendAuditLog } from '../services/audit.js';
 import { embed } from '../services/embeddings.js';
 import { persistTaskSubmission } from '../services/storage.js';
@@ -840,6 +842,20 @@ app.post('/:id/dispute', authMiddleware, async (c) => {
     payload: { disputeId: dispute.id, reason: parsed.data.reason },
   });
 
+  // Check if dispute should be escalated (high-value or repeated failures)
+  const [taskForEscalation] = await db.select({ budgetMax: tasks.budgetMax }).from(tasks).where(eq(tasks.id, id)).limit(1);
+  if (taskForEscalation && await shouldEscalate(id, taskForEscalation.budgetMax)) {
+    await db.update(disputes).set({ status: DISPUTE_STATUS.ESCALATED, updatedAt: new Date() }).where(eq(disputes.id, dispute.id));
+    sendEscalationNotification({
+      disputeId: dispute.id,
+      taskId: id,
+      amount: taskForEscalation.budgetMax.toString(),
+      reason: parsed.data.reason,
+      raisedBy: agent.agent_id,
+      against: againstAgentId ?? null,
+    }).catch((err) => console.error('[ESCALATION] notification failed:', err));
+  }
+
   return c.json(dispute, 201);
 });