feat: initial open-source release

OpenClaw Mission Control — agent orchestration dashboard.

Built with Next.js 16, React 19, TypeScript, SQLite, and Tailwind CSS.
MIT License.

.env.example

@@ -0,0 +1,89 @@
+# === Authentication ===
+# Admin user seeded on first run (only if no users exist in DB)
+AUTH_USER=admin
+AUTH_PASS=change-me-on-first-login
+
+# API key for headless/external access (x-api-key header)
+API_KEY=generate-a-random-key
+
+# Primary gateway defaults (used by /api/gateways seeding if DB is empty)
+MC_DEFAULT_GATEWAY_NAME=primary
+
+# Session cookie behavior
+# - In production, cookies default to secure=true unless overridden.
+# - SameSite defaults to "strict".
+MC_COOKIE_SECURE=
+MC_COOKIE_SAMESITE=strict
+
+# Network access control (middleware)
+# In production, access is blocked unless the host is explicitly allowed.
+# Patterns supported:
+# - Exact hosts: "app.example.com"
+# - Subdomains: "*.example.com"
+# - Prefix wildcard: "100.*" (useful for Tailscale IPs)
+MC_ALLOW_ANY_HOST=
+MC_ALLOWED_HOSTS=localhost,127.0.0.1
+
+# Google OAuth client IDs for Google Sign-In approval workflow
+# Create in Google Cloud Console (Web application) and set authorized origins/redirects
+GOOGLE_CLIENT_ID=
+NEXT_PUBLIC_GOOGLE_CLIENT_ID=
+
+# Legacy cookie auth (backward compat, can be removed once all clients use session auth)
+AUTH_SECRET=random-secret-for-legacy-cookies
+
+# Coordinator identity (used for coordinator chat status replies and comms UI)
+MC_COORDINATOR_AGENT=coordinator
+NEXT_PUBLIC_COORDINATOR_AGENT=coordinator
+
+# === 1Password Integration (optional) ===
+# Vault name for 1Password CLI pulls (used by Integrations panel)
+OP_VAULT_NAME=default
+
+# === OpenClaw Integration ===
+# Path to .openclaw home directory (required for memory browser, gateway config, logs)
+OPENCLAW_HOME=
+# Optional: explicitly point at openclaw.json
+# OPENCLAW_CONFIG_PATH=
+
+# Gateway connection (used by frontend WebSocket)
+OPENCLAW_GATEWAY_HOST=127.0.0.1
+OPENCLAW_GATEWAY_PORT=18789
+# Optional: token used by server-side gateway calls
+OPENCLAW_GATEWAY_TOKEN=
+
+# Frontend env vars (NEXT_PUBLIC_ prefix = available in browser)
+NEXT_PUBLIC_GATEWAY_HOST=
+NEXT_PUBLIC_GATEWAY_PORT=18789
+NEXT_PUBLIC_GATEWAY_PROTOCOL=
+NEXT_PUBLIC_GATEWAY_URL=
+# NEXT_PUBLIC_GATEWAY_TOKEN=  # Optional, set if gateway requires auth token
+
+# === Data Paths (all optional, defaults to .data/ in project root) ===
+# MISSION_CONTROL_DATA_DIR=.data
+# MISSION_CONTROL_DB_PATH=.data/mission-control.db
+# MISSION_CONTROL_TOKENS_PATH=.data/mission-control-tokens.json
+
+# === OpenClaw Paths (derived from OPENCLAW_HOME if not set) ===
+# OPENCLAW_LOG_DIR=/home/openclaw/.openclaw/logs
+# OPENCLAW_MEMORY_DIR=/home/openclaw/.openclaw/memory
+# OPENCLAW_SOUL_TEMPLATES_DIR=/home/openclaw/.openclaw/templates/souls
+# OPENCLAW_BIN=openclaw
+
+# === Super Admin / Provisioning (optional) ===
+# Path to this repo root, needed if you use the super-admin provisioning helpers.
+# MISSION_CONTROL_REPO_ROOT=/path/to/mission-control
+# Template openclaw.json used to seed new tenant state (required for tenant bootstrap).
+# MC_SUPER_TEMPLATE_OPENCLAW_JSON=/path/to/openclaw.json
+# Base path used for provisioned linux user homes (default: /home)
+# MC_TENANT_HOME_ROOT=/home
+# Workspace directory name under each tenant user home (default: workspace)
+# MC_TENANT_WORKSPACE_DIRNAME=workspace
+
+# === Data Retention (days, 0 = keep forever) ===
+# MC_RETAIN_ACTIVITIES_DAYS=90
+# MC_RETAIN_AUDIT_DAYS=365
+# MC_RETAIN_LOGS_DAYS=30
+# MC_RETAIN_NOTIFICATIONS_DAYS=60
+# MC_RETAIN_PIPELINE_RUNS_DAYS=90
+# MC_RETAIN_TOKEN_USAGE_DAYS=90

.gitattributes

@@ -0,0 +1,2 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+# Summary
+Describe what changed and why.
+
+# Risk Level
+Low / Medium / High (pick one)
+
+# Tests
+List commands run and results.
+
+# Contribution Checklist
+- [ ] Tests added/updated for behavior changes
+- [ ] Lint/typecheck/build passing
+- [ ] Security review done if auth/data/crypto touched
+- [ ] DB migration tested if schema changed
+
+# Notes
+Anything reviewers should know.

.github/workflows/quality-gate.yml

@@ -0,0 +1,49 @@
+name: Quality Gate
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: quality-gate-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Unit tests
+        run: pnpm test
+
+      - name: E2E tests
+        run: pnpm test:e2e
+
+      - name: Build
+        run: pnpm build

.gitignore

@@ -0,0 +1,34 @@
+# Dependencies
+node_modules/
+
+# Next.js
+.next/
+out/
+
+# Production
+build/
+dist/
+
+# Misc
+.DS_Store
+*.pem
+.env*.local
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+.env
+.data/
+aegis/
+
+# Claude Code context files
+CLAUDE.md
+**/CLAUDE.md

.npmrc

@@ -0,0 +1,2 @@
+onlyBuiltDependenciesFile=
+ignore-scripts=false

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to Mission Control
+
+Thank you for your interest in contributing to Mission Control.
+
+## Getting Started
+
+```bash
+# Clone the repo
+git clone https://github.com/builderz-labs/mission-control.git
+cd mission-control
+
+# Install dependencies
+pnpm install
+
+# Copy environment config
+cp .env.example .env
+# Edit .env with your values
+
+# Start development server
+pnpm dev
+```
+
+## Development Workflow
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make your changes — keep commits focused and descriptive.
+3. Run the quality gate before submitting:
+   ```bash
+   pnpm quality:gate  # lint + typecheck + test + e2e + build
+   ```
+4. Open a pull request against `main` using the PR template.
+
+## Code Style
+
+- TypeScript strict mode — no `any` unless absolutely necessary.
+- Tailwind CSS for styling — use semantic design tokens (`text-foreground`, `bg-card`, etc.).
+- Server components by default; `'use client'` only when needed.
+- API routes use `requireRole()` for auth and return JSON responses.
+
+## Project Structure
+
+- `src/app/api/` — Next.js API routes (REST endpoints)
+- `src/components/panels/` — Feature panels rendered by the SPA shell
+- `src/components/layout/` — Navigation, header, and layout components
+- `src/lib/` — Shared utilities (auth, database, config, scheduler)
+- `src/store/` — Zustand state management
+
+## Testing
+
+- **Unit tests**: Vitest — `pnpm test`
+- **E2E tests**: Playwright — `pnpm test:e2e`
+- **Type checking**: `pnpm typecheck`
+- **Lint**: `pnpm lint`
+
+## Reporting Bugs
+
+Open an issue with:
+- Steps to reproduce
+- Expected vs actual behavior
+- Browser/OS/Node version
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Builderz Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,293 @@
+<div align="center">
+
+# Mission Control
+
+**The open-source dashboard for AI agent orchestration.**
+
+Manage agent fleets, track tasks, monitor costs, and orchestrate workflows — all from a single pane of glass.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Next.js 16](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org/)
+[![React 19](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=white)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://typescriptlang.org/)
+[![SQLite](https://img.shields.io/badge/SQLite-WAL-003B57?logo=sqlite&logoColor=white)](https://sqlite.org/)
+
+</div>
+
+---
+
+## Why Mission Control?
+
+Running AI agents at scale means juggling sessions, tasks, costs, and reliability across multiple models and channels. Mission Control gives you:
+
+- **20+ panels** — Tasks, agents, logs, tokens, memory, cron, alerts, webhooks, pipelines, and more
+- **Real-time everything** — WebSocket + SSE push updates, smart polling that pauses when you're away
+- **Zero external dependencies** — SQLite database, single `pnpm start` to run, no Redis/Postgres/Docker required
+- **Role-based access** — Viewer, operator, and admin roles with session + API key auth
+- **Quality gates** — Built-in review system that blocks task completion without sign-off
+- **Multi-gateway** — Connect to multiple OpenClaw gateways simultaneously
+
+## Quick Start
+
+```bash
+git clone https://github.com/builderz-labs/mission-control.git
+cd mission-control
+pnpm install
+cp .env.example .env    # edit with your values
+pnpm dev                # http://localhost:3000
+```
+
+Initial login is seeded from `AUTH_USER` / `AUTH_PASS` on first run.
+
+## Features
+
+### Agent Management
+Monitor agent status, spawn new sessions, view heartbeats, and manage the full agent lifecycle from registration to retirement.
+
+### Task Board
+Kanban board with six columns (inbox → backlog → todo → in-progress → review → done), drag-and-drop, priority levels, assignments, and threaded comments.
+
+### Real-time Monitoring
+Live activity feed, session inspector, and log viewer with filtering. WebSocket connection to OpenClaw gateway for instant event delivery.
+
+### Cost Tracking
+Token usage dashboard with per-model breakdowns, trend charts, and cost analysis powered by Recharts.
+
+### Background Automation
+Scheduled tasks for database backups, stale record cleanup, and agent heartbeat monitoring. Configurable via UI or API.
+
+### Integrations
+Outbound webhooks with delivery history, configurable alert rules with cooldowns, and multi-gateway connection management. Optional 1Password CLI integration for secret management.
+
+## Architecture
+
+```
+mission-control/
+├── middleware.ts              # Auth gate + network access control
+├── src/
+│   ├── app/
+│   │   ├── page.tsx           # SPA shell — routes all panels
+│   │   ├── login/page.tsx     # Login page
+│   │   └── api/               # 25+ REST API routes
+│   ├── components/
+│   │   ├── layout/            # NavRail, HeaderBar, LiveFeed
+│   │   ├── dashboard/         # Overview dashboard
+│   │   ├── panels/            # 23 feature panels
+│   │   └── chat/              # Agent chat UI
+│   ├── lib/
+│   │   ├── auth.ts            # Session + API key auth, RBAC
+│   │   ├── db.ts              # SQLite (better-sqlite3, WAL mode)
+│   │   ├── migrations.ts      # 11 schema migrations
+│   │   ├── scheduler.ts       # Background task scheduler
+│   │   ├── webhooks.ts        # Outbound webhook delivery
+│   │   └── websocket.ts       # Gateway WebSocket client
+│   └── store/index.ts         # Zustand state management
+└── .data/                     # Runtime data (SQLite DB, token logs)
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js 16 (App Router) |
+| UI | React 19, Tailwind CSS 3.4 |
+| Language | TypeScript 5.7 |
+| Database | SQLite via better-sqlite3 (WAL mode) |
+| State | Zustand 5 |
+| Charts | Recharts 3 |
+| Real-time | WebSocket + Server-Sent Events |
+| Auth | scrypt hashing, session tokens, RBAC |
+| Testing | Vitest + Playwright |
+
+## Authentication
+
+Three auth methods, three roles:
+
+| Method | Details |
+|--------|---------|
+| Session cookie | `POST /api/auth/login` sets `mc-session` (7-day expiry) |
+| API key | `x-api-key` header matches `API_KEY` env var |
+| Google Sign-In | OAuth with admin approval workflow |
+
+| Role | Access |
+|------|--------|
+| `viewer` | Read-only |
+| `operator` | Read + write (tasks, agents, chat) |
+| `admin` | Full access (users, settings, system ops) |
+
+## API Reference
+
+All endpoints require authentication unless noted. Full reference below.
+
+<details>
+<summary><strong>Auth</strong></summary>
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/auth/login` | Login with username/password |
+| `POST` | `/api/auth/google` | Google Sign-In |
+| `POST` | `/api/auth/logout` | Destroy session |
+| `GET` | `/api/auth/me` | Current user info |
+| `GET` | `/api/auth/access-requests` | List pending access requests (admin) |
+| `POST` | `/api/auth/access-requests` | Approve/reject requests (admin) |
+
+</details>
+
+<details>
+<summary><strong>Core Resources</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET` | `/api/agents` | viewer | List agents with task stats |
+| `POST` | `/api/agents` | operator | Register/update agent |
+| `GET` | `/api/tasks` | viewer | List tasks (filter: `?status=`, `?assigned_to=`, `?priority=`) |
+| `POST` | `/api/tasks` | operator | Create task |
+| `GET` | `/api/tasks/[id]` | viewer | Task details |
+| `PUT` | `/api/tasks/[id]` | operator | Update task |
+| `DELETE` | `/api/tasks/[id]` | admin | Delete task |
+| `GET` | `/api/tasks/[id]/comments` | viewer | Task comments |
+| `POST` | `/api/tasks/[id]/comments` | operator | Add comment |
+| `POST` | `/api/tasks/[id]/broadcast` | operator | Broadcast task to agents |
+
+</details>
+
+<details>
+<summary><strong>Monitoring</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET` | `/api/status` | viewer | System status (uptime, memory, disk) |
+| `GET` | `/api/activities` | viewer | Activity feed |
+| `GET` | `/api/notifications` | viewer | Notifications for recipient |
+| `GET` | `/api/sessions` | viewer | Active gateway sessions |
+| `GET` | `/api/tokens` | viewer | Token usage and cost data |
+| `GET` | `/api/standup` | viewer | Standup report history |
+| `POST` | `/api/standup` | operator | Generate standup |
+
+</details>
+
+<details>
+<summary><strong>Configuration</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET/PUT` | `/api/settings` | admin | App settings |
+| `GET/PUT` | `/api/gateway-config` | admin | OpenClaw gateway config |
+| `GET/POST` | `/api/cron` | admin | Cron management |
+
+</details>
+
+<details>
+<summary><strong>Operations</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET/POST` | `/api/scheduler` | admin | Background task scheduler |
+| `GET` | `/api/audit` | admin | Audit log |
+| `GET` | `/api/logs` | viewer | Agent log browser |
+| `GET` | `/api/memory` | viewer | Memory file browser/search |
+| `GET` | `/api/search` | viewer | Global search |
+| `GET` | `/api/export` | admin | CSV export |
+
+</details>
+
+<details>
+<summary><strong>Integrations</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET/POST/PUT/DELETE` | `/api/webhooks` | admin | Webhook CRUD |
+| `POST` | `/api/webhooks/test` | admin | Test delivery |
+| `GET` | `/api/webhooks/deliveries` | admin | Delivery history |
+| `GET/POST/PUT/DELETE` | `/api/alerts` | admin | Alert rules |
+| `GET/POST/PUT/DELETE` | `/api/gateways` | admin | Gateway connections |
+| `GET/PUT/DELETE/POST` | `/api/integrations` | admin | Integration management |
+
+</details>
+
+<details>
+<summary><strong>Chat & Real-time</strong></summary>
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/events` | SSE stream of DB changes |
+| `GET/POST` | `/api/chat/conversations` | Conversation CRUD |
+| `GET/POST` | `/api/chat/messages` | Message CRUD |
+
+</details>
+
+<details>
+<summary><strong>Agent Lifecycle</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `POST` | `/api/spawn` | operator | Spawn agent session |
+| `POST` | `/api/agents/[id]/heartbeat` | operator | Agent heartbeat |
+| `POST` | `/api/agents/[id]/wake` | operator | Wake sleeping agent |
+| `POST` | `/api/quality-review` | operator | Submit quality review |
+
+</details>
+
+<details>
+<summary><strong>Pipelines</strong></summary>
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| `GET` | `/api/pipelines` | viewer | List pipeline runs |
+| `POST` | `/api/pipelines/run` | operator | Start pipeline |
+| `GET/POST` | `/api/workflows` | viewer/admin | Workflow templates |
+
+</details>
+
+## Environment Variables
+
+See [`.env.example`](.env.example) for the complete list. Key variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AUTH_USER` | No | Initial admin username (default: `admin`) |
+| `AUTH_PASS` | No | Initial admin password |
+| `API_KEY` | No | API key for headless access |
+| `OPENCLAW_HOME` | Yes* | Path to `.openclaw` directory |
+| `OPENCLAW_GATEWAY_HOST` | No | Gateway host (default: `127.0.0.1`) |
+| `OPENCLAW_GATEWAY_PORT` | No | Gateway WebSocket port (default: `18789`) |
+| `MC_ALLOWED_HOSTS` | No | Host allowlist for production |
+
+*Memory browser, log viewer, and gateway config require `OPENCLAW_HOME`.
+
+## Deployment
+
+```bash
+# Build
+pnpm install --frozen-lockfile
+pnpm build
+
+# Run
+OPENCLAW_HOME=/path/to/.openclaw pnpm start
+```
+
+Network access is restricted by default in production. Set `MC_ALLOWED_HOSTS` (comma-separated) or `MC_ALLOW_ANY_HOST=1` to control access.
+
+## Development
+
+```bash
+pnpm dev              # Dev server
+pnpm build            # Production build
+pnpm typecheck        # TypeScript check
+pnpm lint             # ESLint
+pnpm test             # Vitest unit tests
+pnpm test:e2e         # Playwright E2E
+pnpm quality:gate     # All checks
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
+
+## Security
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) &copy; 2026 [Builderz Labs](https://github.com/builderz-labs)

SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Mission Control, please report it responsibly.
+
+**Do not open a public issue.** Instead, email security@builderz.dev with:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and aim to provide a fix or mitigation within 7 days for critical issues.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| latest `main` | Yes |
+| older releases | Best effort |
+
+## Security Considerations
+
+Mission Control handles authentication credentials and API keys. When deploying:
+
+- Always set strong values for `AUTH_PASS` and `API_KEY`.
+- Use `MC_ALLOWED_HOSTS` to restrict network access in production.
+- Keep `.env` files out of version control (already in `.gitignore`).
+- Enable `MC_COOKIE_SECURE=true` when serving over HTTPS.
+- Review the [Environment Variables](README.md#environment-variables) section for all security-relevant configuration.

eslint.config.mjs

@@ -0,0 +1,23 @@
+import next from 'eslint-config-next'
+
+const config = [
+  ...next,
+  {
+    ignores: [
+      '.data/**',
+      'ops/**',
+    ],
+  },
+  // The React 19/ESLint ecosystem is still settling. These rules are valuable,
+  // but they currently trigger a lot of false positives in this codebase.
+  // Keep them off until we do a dedicated refactor pass.
+  {
+    rules: {
+      'react-hooks/set-state-in-effect': 'off',
+      'react-hooks/purity': 'off',
+      'react-hooks/immutability': 'off',
+    },
+  },
+]
+
+export default config

middleware.ts

@@ -0,0 +1,100 @@
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+function envFlag(name: string): boolean {
+  const raw = process.env[name]
+  if (raw === undefined) return false
+  const v = String(raw).trim().toLowerCase()
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on'
+}
+
+function getRequestHostname(request: NextRequest): string {
+  const raw = request.headers.get('x-forwarded-host') || request.headers.get('host') || ''
+  // If multiple hosts are present, take the first (proxy chain).
+  const first = raw.split(',')[0] || ''
+  return first.trim().split(':')[0] || ''
+}
+
+function hostMatches(pattern: string, hostname: string): boolean {
+  const p = pattern.trim().toLowerCase()
+  const h = hostname.trim().toLowerCase()
+  if (!p || !h) return false
+
+  // "*.example.com" matches "a.example.com" (but not bare "example.com")
+  if (p.startsWith('*.')) {
+    const suffix = p.slice(2)
+    return h.endsWith(`.${suffix}`)
+  }
+
+  // "100.*" matches "100.64.0.1"
+  if (p.endsWith('.*')) {
+    const prefix = p.slice(0, -1)
+    return h.startsWith(prefix)
+  }
+
+  return h === p
+}
+
+export function middleware(request: NextRequest) {
+  // Network access control.
+  // In production: default-deny unless explicitly allowed.
+  // In dev/test: allow all hosts unless overridden.
+  const hostName = getRequestHostname(request)
+  const allowAnyHost = envFlag('MC_ALLOW_ANY_HOST') || process.env.NODE_ENV !== 'production'
+  const allowedPatterns = String(process.env.MC_ALLOWED_HOSTS || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+
+  const isAllowedHost = allowAnyHost || allowedPatterns.some((p) => hostMatches(p, hostName))
+
+  if (!isAllowedHost) {
+    return new NextResponse('Forbidden', { status: 403 })
+  }
+
+  const { pathname } = request.nextUrl
+
+  // Allow login page and auth API without session
+  if (pathname === '/login' || pathname.startsWith('/api/auth/')) {
+    return NextResponse.next()
+  }
+
+  // Check for session cookie
+  const sessionToken = request.cookies.get('mc-session')?.value
+
+  // API routes: accept session cookie OR API key
+  if (pathname.startsWith('/api/')) {
+    const apiKey = request.headers.get('x-api-key')
+    if (sessionToken || (apiKey && apiKey === process.env.API_KEY)) {
+      return NextResponse.next()
+    }
+
+    // Backward compat: accept legacy cookie during migration
+    const legacyCookie = request.cookies.get('mission-control-auth')
+    if (legacyCookie?.value === process.env.AUTH_SECRET) {
+      return NextResponse.next()
+    }
+
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  // Page routes: redirect to login if no session
+  if (sessionToken) {
+    return NextResponse.next()
+  }
+
+  // Backward compat: accept legacy cookie
+  const legacyCookie = request.cookies.get('mission-control-auth')
+  if (legacyCookie?.value === process.env.AUTH_SECRET) {
+    return NextResponse.next()
+  }
+
+  // Redirect to login
+  const loginUrl = request.nextUrl.clone()
+  loginUrl.pathname = '/login'
+  return NextResponse.redirect(loginUrl)
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
+}

next.config.js

@@ -0,0 +1,46 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  turbopack: {},
+  
+  // Security headers
+  async headers() {
+    const googleEnabled = !!(process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID || process.env.GOOGLE_CLIENT_ID)
+
+    const csp = [
+      `default-src 'self'`,
+      `script-src 'self' 'unsafe-inline' 'unsafe-eval'${googleEnabled ? ' https://accounts.google.com' : ''}`,
+      `style-src 'self' 'unsafe-inline'`,
+      `connect-src 'self' ws: wss: http://127.0.0.1:* http://localhost:*`,
+      `img-src 'self' data: blob:${googleEnabled ? ' https://*.googleusercontent.com https://lh3.googleusercontent.com' : ''}`,
+      `font-src 'self' data:`,
+      `frame-src 'self'${googleEnabled ? ' https://accounts.google.com' : ''}`,
+    ].join('; ')
+
+    return [
+      {
+        source: '/:path*',
+        headers: [
+          { key: 'X-Frame-Options', value: 'DENY' },
+          { key: 'X-Content-Type-Options', value: 'nosniff' },
+          { key: 'X-XSS-Protection', value: '1; mode=block' },
+          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+          { key: 'Content-Security-Policy', value: csp },
+          { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+        ],
+      },
+    ];
+  },
+  
+  webpack: (config) => {
+    config.resolve.fallback = {
+      ...config.resolve.fallback,
+      net: false,
+      os: false,
+      fs: false,
+      path: false,
+    };
+    return config;
+  },
+};
+
+module.exports = nextConfig;

ops/mc-provisioner-daemon.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const net = require('net')
+const { spawn } = require('child_process')
+const path = require('path')
+
+const SOCKET_PATH = process.env.MC_PROVISIONER_SOCKET || '/run/mc-provisioner.sock'
+const TOKEN = String(process.env.MC_PROVISIONER_TOKEN || '')
+const SOCKET_GROUP = process.env.MC_PROVISIONER_GROUP || 'openclaw'
+const REPO_ROOT = process.env.MISSION_CONTROL_REPO_ROOT || path.resolve(__dirname, '..')
+const DATA_DIR = process.env.MISSION_CONTROL_DATA_DIR || path.join(REPO_ROOT, '.data')
+const TENANT_HOME_ROOT = String(process.env.MC_TENANT_HOME_ROOT || '/home').trim() || '/home'
+const TENANT_WORKSPACE_DIRNAME = String(process.env.MC_TENANT_WORKSPACE_DIRNAME || 'workspace').trim() || 'workspace'
+const TEMPLATE_OPENCLAW_JSON = process.env.MC_SUPER_TEMPLATE_OPENCLAW_JSON || (process.env.OPENCLAW_HOME ? path.join(process.env.OPENCLAW_HOME, 'openclaw.json') : '')
+const GATEWAY_SYSTEMD_TEMPLATE = path.join(REPO_ROOT, 'ops', 'templates', 'openclaw-gateway@.service')
+
+if (!TOKEN) {
+  console.error('MC_PROVISIONER_TOKEN is required')
+  process.exit(1)
+}
+
+function escapeRegExp(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function isSafeUser(user) {
+  return /^[a-z_][a-z0-9_-]{1,30}$/.test(user)
+}
+
+function pathJoinPosix(...parts) {
+  // Use posix paths for allowlisting because provisioner executes linux commands.
+  const cleaned = parts.map((p) => String(p || '').replace(/\/+$/g, ''))
+  return path.posix.join(...cleaned)
+}
+
+function isSafeHomePath(path, user, suffix) {
+  return path === pathJoinPosix(TENANT_HOME_ROOT, user, suffix)
+}
+
+function validateCommand(command, args) {
+  const cmd = String(command || '').split('/').pop()
+  if (!command || !Array.isArray(args)) return 'Invalid command payload'
+
+  if (cmd === 'useradd') {
+    if (args.length !== 4) return 'useradd argument mismatch'
+    const [a, b, shell, user] = args
+    if (a !== '-m' || b !== '-s' || shell !== '/bin/bash') return 'useradd args not allowed'
+    if (!isSafeUser(user)) return 'Invalid username'
+    return null
+  }
+
+  if (cmd === 'install') {
+    if (args.length !== 8) return 'install argument mismatch'
+    const [d, mFlag, mode, oFlag, userA, gFlag, userB, target] = args
+    if (d !== '-d' || mFlag !== '-m' || oFlag !== '-o' || gFlag !== '-g') return 'install args not allowed'
+    if (!['0750', '0700'].includes(mode)) return 'install mode not allowed'
+    const isRootOwned = userA === 'root' && userB === 'root'
+    const isTenantOwned = isSafeUser(userA) && isSafeUser(userB) && userA === userB
+    if (!isRootOwned && !isTenantOwned) return 'install ownership not allowed'
+    const openclawPath = pathJoinPosix(TENANT_HOME_ROOT, userA, '.openclaw')
+    const workspacePath = pathJoinPosix(TENANT_HOME_ROOT, userA, TENANT_WORKSPACE_DIRNAME)
+    if (isRootOwned && target === '/etc/openclaw-tenants') return null
+    if (![openclawPath, workspacePath].includes(target)) return 'install path not allowed'
+    return null
+  }
+
+  if (cmd === 'cp') {
+    if (args.length !== 3) return 'cp argument mismatch'
+    const [flag, source, target] = args
+    if (!['-n', '-f'].includes(flag)) return 'cp flag not allowed'
+    if (TEMPLATE_OPENCLAW_JSON && source === TEMPLATE_OPENCLAW_JSON) {
+      if (flag !== '-n') return 'openclaw config copy must use -n'
+      const homeRootRe = escapeRegExp(pathJoinPosix(TENANT_HOME_ROOT))
+      const match = new RegExp(`^${homeRootRe}\\/([a-z_][a-z0-9_-]{1,30})\\/\\.openclaw\\/openclaw\\.json$`).exec(target)
+      if (!match) return 'cp target not allowed'
+      return null
+    }
+    if (source === GATEWAY_SYSTEMD_TEMPLATE) {
+      if (flag !== '-n') return 'template copy must use -n'
+      if (target !== '/etc/systemd/system/openclaw-gateway@.service') return 'gateway template target not allowed'
+      return null
+    }
+    const provisionerEnvRe = new RegExp(`^${escapeRegExp(path.join(DATA_DIR, 'provisioner'))}\\/([a-z0-9-]{3,32})\\/openclaw-gateway\\.env$`)
+    if (provisionerEnvRe.test(source)) {
+      if (flag !== '-f') return 'tenant env copy must use -f'
+      if (!/^\/etc\/openclaw-tenants\/[a-z_][a-z0-9_-]{1,30}\.env$/.test(target)) return 'tenant env target not allowed'
+      return null
+    }
+    return 'cp source not allowed'
+  }
+
+  if (cmd === 'chown') {
+    if (args.length !== 3) return 'chown argument mismatch'
+    const [rFlag, owner, target] = args
+    if (rFlag !== '-R') return 'chown must use -R'
+    const [userA, userB] = owner.split(':')
+    if (!isSafeUser(userA) || userA !== userB) return 'chown owner not allowed'
+    if (target !== pathJoinPosix(TENANT_HOME_ROOT, userA)) return 'chown target not allowed'
+    return null
+  }
+
+  if (cmd === 'rm') {
+    if (args.length !== 2) return 'rm argument mismatch'
+    const [flag, target] = args
+
+    if (flag === '-f') {
+      if (!/^\/etc\/openclaw-tenants\/[a-z_][a-z0-9_-]{1,30}\.env$/.test(target)) {
+        return 'rm -f target not allowed'
+      }
+      return null
+    }
+
+    if (flag === '-rf') {
+      const homeRootRe = escapeRegExp(pathJoinPosix(TENANT_HOME_ROOT))
+      const ws = escapeRegExp(TENANT_WORKSPACE_DIRNAME)
+      const match = new RegExp(`^${homeRootRe}\\/([a-z_][a-z0-9_-]{1,30})\\/(\\.openclaw|${ws})$`).exec(target)
+      if (!match) return 'rm -rf target not allowed'
+      return null
+    }
+
+    return 'rm flag not allowed'
+  }
+
+  if (cmd === 'userdel') {
+    if (args.length !== 2) return 'userdel argument mismatch'
+    if (args[0] !== '-r') return 'userdel must use -r'
+    if (!isSafeUser(args[1])) return 'Invalid username'
+    return null
+  }
+
+  if (cmd === 'true') {
+    if (args.length !== 0) return 'true takes no args'
+    return null
+  }
+
+  if (cmd === 'systemctl') {
+    if (args.length === 1 && args[0] === 'daemon-reload') return null
+    if (args.length === 3 && args[0] === 'enable' && args[1] === '--now') {
+      if (/^openclaw-gateway@[a-z_][a-z0-9_-]{1,30}\.service$/.test(args[2])) return null
+      return 'systemctl service name not allowed'
+    }
+    if (args.length === 3 && args[0] === 'disable' && args[1] === '--now') {
+      if (/^openclaw-gateway@[a-z_][a-z0-9_-]{1,30}\.service$/.test(args[2])) return null
+      return 'systemctl service name not allowed'
+    }
+    return 'systemctl args not allowed'
+  }
+
+  return `Command not allowlisted: ${command}`
+}
+
+function run(command, args, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { shell: false })
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGKILL')
+    }, Math.max(1000, Number(timeoutMs || 10000)))
+
+    child.stdout.on('data', (d) => { stdout += d.toString('utf8') })
+    child.stderr.on('data', (d) => { stderr += d.toString('utf8') })
+
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      resolve({
+        ok: !timedOut && code === 0,
+        code: timedOut ? 124 : code,
+        stdout,
+        stderr: timedOut ? `${stderr}\nTimed out` : stderr,
+      })
+    })
+
+    child.on('error', (err) => {
+      clearTimeout(timer)
+      resolve({ ok: false, code: 1, stdout, stderr: `${stderr}\n${err.message}` })
+    })
+  })
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function runWithRetry(command, args, timeoutMs) {
+  const cmd = String(command || '').split('/').pop()
+  const maxAttempts = cmd === 'useradd' ? 6 : 1
+  let last = null
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const result = await run(command, args, timeoutMs)
+    last = result
+    if (result.ok) return result
+
+    const transientLock =
+      cmd === 'useradd' &&
+      /cannot lock \/etc\/passwd/i.test(String(result.stderr || ''))
+
+    if (!transientLock || attempt === maxAttempts) {
+      return result
+    }
+    await sleep(800)
+  }
+
+  return last || { ok: false, code: 1, stdout: '', stderr: 'Unknown execution failure' }
+}
+
+function writeResp(socket, obj) {
+  try {
+    socket.write(JSON.stringify(obj) + '\n')
+  } catch {
+    // no-op
+  } finally {
+    socket.end()
+  }
+}
+
+if (fs.existsSync(SOCKET_PATH)) {
+  try {
+    fs.unlinkSync(SOCKET_PATH)
+  } catch (err) {
+    console.error(`Failed to remove stale socket ${SOCKET_PATH}:`, err.message)
+    process.exit(1)
+  }
+}
+
+const server = net.createServer((socket) => {
+  let buf = ''
+
+  socket.on('data', async (chunk) => {
+    buf += chunk.toString('utf8')
+    const idx = buf.indexOf('\n')
+    if (idx === -1) return
+
+    const line = buf.slice(0, idx)
+    buf = buf.slice(idx + 1)
+
+    let req
+    try {
+      req = JSON.parse(line)
+    } catch {
+      writeResp(socket, { ok: false, error: 'Invalid JSON' })
+      return
+    }
+
+    if (!req || req.token !== TOKEN) {
+      writeResp(socket, { ok: false, error: 'Unauthorized' })
+      return
+    }
+
+    const command = String(req.command || '')
+    const args = Array.isArray(req.args) ? req.args.map((a) => String(a)) : []
+    const dryRun = !!req.dryRun
+    const timeoutMs = Number(req.timeoutMs || 10000)
+
+    const validationErr = validateCommand(command, args)
+    if (validationErr) {
+      writeResp(socket, { ok: false, error: validationErr })
+      return
+    }
+
+    if (dryRun) {
+      writeResp(socket, { ok: true, code: 0, stdout: '', stderr: '', skipped: true })
+      return
+    }
+
+    const result = await runWithRetry(command, args, timeoutMs)
+    if (!result.ok) {
+      writeResp(socket, { ok: false, code: result.code, stdout: result.stdout, stderr: result.stderr, error: `Command failed: ${command}` })
+      return
+    }
+
+    writeResp(socket, { ok: true, code: result.code, stdout: result.stdout, stderr: result.stderr, skipped: false })
+  })
+})
+
+server.listen(SOCKET_PATH, () => {
+  fs.chmodSync(SOCKET_PATH, 0o660)
+  try {
+    const group = require('child_process').execSync(`getent group ${SOCKET_GROUP} | cut -d: -f3`).toString('utf8').trim()
+    const gid = Number(group)
+    if (Number.isInteger(gid)) {
+      fs.chownSync(SOCKET_PATH, 0, gid)
+    }
+  } catch {
+    // fallback: keep root:root
+  }
+  console.log(`mc-provisioner listening on ${SOCKET_PATH}`)
+})
+
+function shutdown() {
+  try { server.close() } catch {}
+  try { fs.unlinkSync(SOCKET_PATH) } catch {}
+  process.exit(0)
+}
+
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)

ops/templates/openclaw-gateway@.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=OpenClaw Gateway (%i)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=%i
+Group=%i
+SupplementaryGroups=docker
+WorkingDirectory=/home/%i
+Environment=HOME=/home/%i
+Environment=PATH=/home/%i/bin:/usr/local/bin:/usr/bin:/bin:/home/%i/.local/bin
+Environment=NODE_OPTIONS=--experimental-sqlite
+EnvironmentFile=-/etc/openclaw-tenants/%i.env
+ExecStart=/usr/local/bin/openclaw gateway --port ${OPENCLAW_GATEWAY_PORT}
+Restart=always
+RestartSec=5
+NoNewPrivileges=true
+LimitNOFILE=65535
+
+[Install]
+WantedBy=multi-user.target

package.json

@@ -0,0 +1,66 @@
+{
+  "name": "mission-control",
+  "version": "1.0.0",
+  "description": "OpenClaw Mission Control — open-source agent orchestration dashboard",
+  "scripts": {
+    "dev": "next dev --hostname 127.0.0.1",
+    "build": "next build",
+    "start": "next start --hostname 0.0.0.0 --port 3005",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:e2e": "playwright test",
+    "test:all": "pnpm lint && pnpm typecheck && pnpm test && pnpm test:e2e && pnpm build",
+    "quality:gate": "pnpm test:all"
+  },
+  "dependencies": {
+    "@xyflow/react": "^12.10.0",
+    "autoprefixer": "^10.4.20",
+    "better-sqlite3": "^12.6.2",
+    "clsx": "^2.1.1",
+    "eslint": "^9.18.0",
+    "eslint-config-next": "^16.1.6",
+    "next": "^16.1.6",
+    "next-themes": "^0.4.6",
+    "postcss": "^8.5.2",
+    "react": "^19.0.1",
+    "react-dom": "^19.0.1",
+    "reactflow": "^11.11.4",
+    "recharts": "^3.7.0",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "ws": "^8.19.0",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.51.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.10.6",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@types/ws": "^8.18.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "jsdom": "^26.0.0",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^2.1.5"
+  },
+  "keywords": [
+    "openclaw",
+    "agent",
+    "orchestration",
+    "dashboard",
+    "nextjs"
+  ],
+  "author": "Builderz Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/builderz-labs/mission-control.git"
+  }
+}

playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: 'tests',
+  timeout: 60_000,
+  expect: {
+    timeout: 10_000
+  },
+  fullyParallel: true,
+  reporter: [['list']],
+  use: {
+    baseURL: process.env.E2E_BASE_URL || 'http://127.0.0.1:3000',
+    trace: 'retain-on-failure'
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } }
+  ]
+})

postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

scripts/agent-heartbeat.sh

@@ -0,0 +1,240 @@
+#!/bin/bash
+
+# Mission Control Phase 3: Agent Heartbeat Script
+# Called by OpenClaw cron every 15 minutes to wake agents and check for work
+#
+# Usage:
+#   scripts/agent-heartbeat.sh [agent_name]
+#
+# If no agent specified, checks all agents with session keys
+
+set -e
+
+# Configuration
+MISSION_CONTROL_URL="${MISSION_CONTROL_URL:-http://localhost:3005}"
+LOG_DIR="${LOG_DIR:-$HOME/.mission-control/logs}"
+LOG_FILE="$LOG_DIR/agent-heartbeat-$(date +%Y-%m-%d).log"
+MAX_CONCURRENT=3  # Max agents to check concurrently
+OPENCLAW_CMD="${OPENCLAW_CMD:-openclaw}"
+
+# Ensure log directory exists
+mkdir -p "$LOG_DIR"
+
+# Logging function
+log() {
+    local level="$1"
+    shift
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [$level] $*" | tee -a "$LOG_FILE"
+}
+
+# Check if Mission Control is running
+check_mission_control() {
+    if ! curl -s "$MISSION_CONTROL_URL/api/status" > /dev/null 2>&1; then
+        log "ERROR" "Mission Control not accessible at $MISSION_CONTROL_URL"
+        return 1
+    fi
+    return 0
+}
+
+# Check heartbeat for specific agent
+check_agent_heartbeat() {
+    local agent_name="$1"
+    local agent_id="$2"
+    
+    log "INFO" "Checking heartbeat for agent: $agent_name"
+    
+    # Call heartbeat endpoint
+    local response
+    response=$(curl -s -w "HTTP_STATUS:%{http_code}" "$MISSION_CONTROL_URL/api/agents/$agent_id/heartbeat" 2>/dev/null)
+    
+    local http_code
+    http_code=$(echo "$response" | grep -o "HTTP_STATUS:[0-9]*" | cut -d: -f2)
+    local body
+    body=$(echo "$response" | sed 's/HTTP_STATUS:[0-9]*$//')
+    
+    if [[ "$http_code" != "200" ]]; then
+        log "ERROR" "Heartbeat failed for $agent_name: HTTP $http_code"
+        return 1
+    fi
+    
+    # Parse response
+    local status
+    status=$(echo "$body" | jq -r '.status // "unknown"' 2>/dev/null || echo "parse_error")
+    
+    if [[ "$status" == "HEARTBEAT_OK" ]]; then
+        log "INFO" "Agent $agent_name: No work items found"
+        return 0
+    elif [[ "$status" == "WORK_ITEMS_FOUND" ]]; then
+        local total_items
+        total_items=$(echo "$body" | jq -r '.total_items // 0' 2>/dev/null || echo "0")
+        log "INFO" "Agent $agent_name: Found $total_items work items"
+        
+        # If work items found and agent has session key, send wake notification
+        local session_key
+        session_key=$(get_agent_session_key "$agent_name")
+        
+        if [[ -n "$session_key" && "$session_key" != "null" ]]; then
+            send_wake_notification "$agent_name" "$session_key" "$total_items" "$body"
+        else
+            log "WARN" "Agent $agent_name has work items but no session key configured"
+        fi
+        
+        return 0
+    else
+        log "ERROR" "Unexpected heartbeat response for $agent_name: $status"
+        return 1
+    fi
+}
+
+# Get agent session key from database
+get_agent_session_key() {
+    local agent_name="$1"
+    
+    # Query agents API to get session key
+    local agent_data
+    agent_data=$(curl -s "$MISSION_CONTROL_URL/api/agents?limit=100" 2>/dev/null | jq -r ".agents[] | select(.name == \"$agent_name\") | .session_key" 2>/dev/null || echo "")
+    
+    echo "$agent_data"
+}
+
+# Send wake notification to agent session
+send_wake_notification() {
+    local agent_name="$1"
+    local session_key="$2"
+    local work_items_count="$3"
+    local heartbeat_data="$4"
+    
+    log "INFO" "Sending wake notification to $agent_name (session: $session_key)"
+    
+    # Format wake message
+    local wake_message="🤖 **Mission Control Heartbeat**\n\n"
+    wake_message+="Agent: $agent_name\n"
+    wake_message+="Work items found: $work_items_count\n\n"
+    wake_message+="🔔 You have notifications or tasks that need attention.\n"
+    wake_message+="Use Mission Control to view details: $MISSION_CONTROL_URL\n\n"
+    wake_message+="⏰ $(date '+%Y-%m-%d %H:%M:%S')"
+    
+    # Send via OpenClaw sessions_send
+    if "$OPENCLAW_CMD" gateway sessions_send --session "$session_key" --message "$wake_message" >> "$LOG_FILE" 2>&1; then
+        log "INFO" "Wake notification sent successfully to $agent_name"
+    else
+        log "ERROR" "Failed to send wake notification to $agent_name"
+    fi
+}
+
+# Get list of agents to check
+get_agents_to_check() {
+    local filter_agent="$1"
+    
+    if [[ -n "$filter_agent" ]]; then
+        # Check specific agent
+        echo "$filter_agent"
+        return
+    fi
+    
+    # Get all agents with session keys
+    curl -s "$MISSION_CONTROL_URL/api/agents?limit=100" 2>/dev/null | \
+        jq -r '.agents[] | select(.session_key != null and .session_key != "") | .name' 2>/dev/null || \
+        echo ""
+}
+
+# Main execution
+main() {
+    local target_agent="$1"
+    
+    log "INFO" "Starting agent heartbeat check (PID: $$)"
+    
+    # Check if Mission Control is running
+    if ! check_mission_control; then
+        log "ERROR" "Aborting: Mission Control not accessible"
+        exit 1
+    fi
+    
+    # Get agents to check
+    local agents
+    agents=$(get_agents_to_check "$target_agent")
+    
+    if [[ -z "$agents" ]]; then
+        log "WARN" "No agents found with session keys configured"
+        exit 0
+    fi
+    
+    local total_agents
+    total_agents=$(echo "$agents" | wc -l)
+    log "INFO" "Checking heartbeat for $total_agents agent(s)"
+    
+    # Process agents (limit concurrency)
+    local processed=0
+    local successful=0
+    local failed=0
+    local pids=()
+    
+    while IFS= read -r agent_name; do
+        [[ -z "$agent_name" ]] && continue
+        
+        # Wait if we've reached max concurrent processes
+        while [[ ${#pids[@]} -ge $MAX_CONCURRENT ]]; do
+            for i in "${!pids[@]}"; do
+                if ! kill -0 "${pids[$i]}" 2>/dev/null; then
+                    unset "pids[$i]"
+                fi
+            done
+            pids=("${pids[@]}") # Reindex array
+            
+            if [[ ${#pids[@]} -ge $MAX_CONCURRENT ]]; then
+                sleep 1
+            fi
+        done
+        
+        # Start heartbeat check in background
+        (
+            if check_agent_heartbeat "$agent_name" "$agent_name"; then
+                echo "SUCCESS:$agent_name"
+            else
+                echo "FAILED:$agent_name"
+            fi
+        ) &
+        
+        pids+=($!)
+        ((processed++))
+    done <<< "$agents"
+    
+    # Wait for all background processes
+    for pid in "${pids[@]}"; do
+        if wait "$pid"; then
+            ((successful++))
+        else
+            ((failed++))
+        fi
+    done
+    
+    log "INFO" "Heartbeat check completed: $processed processed, $successful successful, $failed failed"
+    
+    # Return appropriate exit code
+    if [[ $failed -gt 0 ]]; then
+        exit 1
+    else
+        exit 0
+    fi
+}
+
+# Handle script arguments
+case "${1:-}" in
+    --help|-h)
+        echo "Mission Control Agent Heartbeat Script"
+        echo ""
+        echo "Usage: $0 [agent_name]"
+        echo ""
+        echo "Options:"
+        echo "  agent_name    Check specific agent only"
+        echo "  --help, -h    Show this help message"
+        echo ""
+        echo "Environment variables:"
+        echo "  MISSION_CONTROL_URL  Mission Control base URL (default: http://localhost:3005)"
+        echo ""
+        exit 0
+        ;;
+    *)
+        main "$@"
+        ;;
+esac

scripts/notification-daemon.sh

@@ -0,0 +1,347 @@
+#!/bin/bash
+
+# Mission Control Phase 3: Notification Delivery Daemon
+# Polls undelivered notifications and sends them to agent sessions via OpenClaw
+#
+# Usage:
+#   scripts/notification-daemon.sh [options]
+#
+# Options:
+#   --agent AGENT_NAME    Only deliver notifications to specific agent
+#   --limit N             Max notifications to process per batch (default: 50)
+#   --dry-run            Test mode - don't actually deliver notifications
+#   --daemon             Run in daemon mode (continuous polling)
+#   --interval SECONDS   Polling interval in daemon mode (default: 60)
+
+set -e
+
+# Configuration
+MISSION_CONTROL_URL="${MISSION_CONTROL_URL:-http://localhost:3005}"
+LOG_DIR="${LOG_DIR:-$HOME/.mission-control/logs}"
+LOG_FILE="$LOG_DIR/notification-daemon-$(date +%Y-%m-%d).log"
+PID_FILE="/tmp/notification-daemon.pid"
+DEFAULT_INTERVAL=60
+DEFAULT_LIMIT=50
+
+# Command line options
+AGENT_FILTER=""
+LIMIT=$DEFAULT_LIMIT
+DRY_RUN=false
+DAEMON_MODE=false
+INTERVAL=$DEFAULT_INTERVAL
+
+# Ensure log directory exists
+mkdir -p "$LOG_DIR"
+
+# Logging function
+log() {
+    local level="$1"
+    shift
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [$level] $*" | tee -a "$LOG_FILE"
+}
+
+# Check if Mission Control is running
+check_mission_control() {
+    if ! curl -s "$MISSION_CONTROL_URL/api/status" > /dev/null 2>&1; then
+        log "ERROR" "Mission Control not accessible at $MISSION_CONTROL_URL"
+        return 1
+    fi
+    return 0
+}
+
+# Process and deliver notifications
+deliver_notifications() {
+    log "INFO" "Starting notification delivery batch"
+    
+    # Build API request
+    local api_payload="{\"limit\": $LIMIT"
+    
+    if [[ -n "$AGENT_FILTER" ]]; then
+        api_payload+=", \"agent_filter\": \"$AGENT_FILTER\""
+    fi
+    
+    if [[ "$DRY_RUN" == "true" ]]; then
+        api_payload+=", \"dry_run\": true"
+    fi
+    
+    api_payload+="}"
+    
+    # Call notification delivery endpoint
+    local response
+    response=$(curl -s -w "HTTP_STATUS:%{http_code}" \
+        -X POST \
+        -H "Content-Type: application/json" \
+        -d "$api_payload" \
+        "$MISSION_CONTROL_URL/api/notifications/deliver" 2>/dev/null)
+    
+    local http_code
+    http_code=$(echo "$response" | grep -o "HTTP_STATUS:[0-9]*" | cut -d: -f2)
+    local body
+    body=$(echo "$response" | sed 's/HTTP_STATUS:[0-9]*$//')
+    
+    if [[ "$http_code" != "200" ]]; then
+        log "ERROR" "Notification delivery failed: HTTP $http_code"
+        log "ERROR" "Response: $body"
+        return 1
+    fi
+    
+    # Parse results
+    local status delivered errors total_processed
+    status=$(echo "$body" | jq -r '.status // "unknown"' 2>/dev/null || echo "parse_error")
+    delivered=$(echo "$body" | jq -r '.delivered // 0' 2>/dev/null || echo "0")
+    errors=$(echo "$body" | jq -r '.errors // 0' 2>/dev/null || echo "0")
+    total_processed=$(echo "$body" | jq -r '.total_processed // 0' 2>/dev/null || echo "0")
+    
+    if [[ "$status" == "success" ]]; then
+        if [[ "$total_processed" -gt 0 ]]; then
+            log "INFO" "Batch completed: $total_processed processed, $delivered delivered, $errors failed"
+            
+            # Log detailed errors if any
+            if [[ "$errors" -gt 0 ]]; then
+                local error_details
+                error_details=$(echo "$body" | jq -r '.error_details[]? | "- \(.recipient): \(.error)"' 2>/dev/null || echo "")
+                if [[ -n "$error_details" ]]; then
+                    log "WARN" "Error details:"
+                    echo "$error_details" | while read -r line; do
+                        log "WARN" "  $line"
+                    done
+                fi
+            fi
+        else
+            log "INFO" "No notifications to deliver"
+        fi
+        
+        return 0
+    else
+        log "ERROR" "Unexpected delivery response: $status"
+        return 1
+    fi
+}
+
+# Get delivery statistics
+get_delivery_stats() {
+    local stats_url="$MISSION_CONTROL_URL/api/notifications/deliver"
+    
+    if [[ -n "$AGENT_FILTER" ]]; then
+        stats_url+="?agent=$AGENT_FILTER"
+    fi
+    
+    local response
+    response=$(curl -s "$stats_url" 2>/dev/null)
+    
+    if [[ $? -eq 0 ]]; then
+        echo "$response" | jq -r '
+            "Delivery Statistics:",
+            "  Total notifications: \(.statistics.total)",
+            "  Delivered: \(.statistics.delivered)",
+            "  Undelivered: \(.statistics.undelivered)",
+            "  Delivery rate: \(.statistics.delivery_rate)%",
+            "",
+            "Agents with pending notifications:",
+            (.agents_with_pending[] | "  \(.recipient): \(.pending_count) pending\(if .session_key then "" else " (no session key)" end)")
+        ' 2>/dev/null || echo "Failed to parse statistics"
+    else
+        echo "Failed to fetch delivery statistics"
+    fi
+}
+
+# Daemon mode signal handlers
+cleanup() {
+    log "INFO" "Received shutdown signal, stopping daemon"
+    rm -f "$PID_FILE"
+    exit 0
+}
+
+# Check if daemon is already running
+check_daemon() {
+    if [[ -f "$PID_FILE" ]]; then
+        local old_pid
+        old_pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
+        
+        if [[ -n "$old_pid" ]] && kill -0 "$old_pid" 2>/dev/null; then
+            log "ERROR" "Notification daemon already running with PID $old_pid"
+            exit 1
+        else
+            log "WARN" "Stale PID file found, removing"
+            rm -f "$PID_FILE"
+        fi
+    fi
+}
+
+# Run in daemon mode
+run_daemon() {
+    log "INFO" "Starting notification daemon (PID: $$)"
+    
+    # Check if already running
+    check_daemon
+    
+    # Write PID file
+    echo $$ > "$PID_FILE"
+    
+    # Set up signal handlers
+    trap cleanup SIGTERM SIGINT SIGQUIT
+    
+    # Main daemon loop
+    while true; do
+        if ! check_mission_control; then
+            log "WARN" "Mission Control not accessible, sleeping $INTERVAL seconds"
+            sleep "$INTERVAL"
+            continue
+        fi
+        
+        # Process notifications
+        if deliver_notifications; then
+            log "DEBUG" "Delivery batch completed successfully"
+        else
+            log "WARN" "Delivery batch had errors"
+        fi
+        
+        # Sleep until next cycle
+        sleep "$INTERVAL"
+    done
+}
+
+# Parse command line arguments
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --agent)
+                AGENT_FILTER="$2"
+                shift 2
+                ;;
+            --limit)
+                LIMIT="$2"
+                shift 2
+                ;;
+            --dry-run)
+                DRY_RUN=true
+                shift
+                ;;
+            --daemon)
+                DAEMON_MODE=true
+                shift
+                ;;
+            --interval)
+                INTERVAL="$2"
+                shift 2
+                ;;
+            --stats)
+                get_delivery_stats
+                exit 0
+                ;;
+            --stop)
+                if [[ -f "$PID_FILE" ]]; then
+                    local pid
+                    pid=$(cat "$PID_FILE" 2>/dev/null || echo "")
+                    if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+                        kill -TERM "$pid"
+                        log "INFO" "Sent stop signal to daemon (PID: $pid)"
+                        exit 0
+                    else
+                        log "WARN" "No running daemon found"
+                        rm -f "$PID_FILE"
+                        exit 1
+                    fi
+                else
+                    log "WARN" "No daemon PID file found"
+                    exit 1
+                fi
+                ;;
+            --help|-h)
+                show_help
+                exit 0
+                ;;
+            *)
+                echo "Unknown option: $1" >&2
+                show_help
+                exit 1
+                ;;
+        esac
+    done
+}
+
+# Show help
+show_help() {
+    cat << 'EOF'
+Mission Control Notification Delivery Daemon
+
+Usage: notification-daemon.sh [options]
+
+Options:
+  --agent AGENT_NAME      Only deliver notifications to specific agent
+  --limit N              Max notifications to process per batch (default: 50)
+  --dry-run              Test mode - don't actually deliver notifications
+  --daemon               Run in daemon mode (continuous polling)
+  --interval SECONDS     Polling interval in daemon mode (default: 60)
+  --stats                Show delivery statistics and exit
+  --stop                 Stop running daemon
+  --help, -h             Show this help message
+
+Examples:
+  # Single batch delivery
+  ./notification-daemon.sh
+
+  # Dry run to test
+  ./notification-daemon.sh --dry-run
+
+  # Deliver only to specific agent
+  ./notification-daemon.sh --agent "coordinator"
+
+  # Run as daemon
+  ./notification-daemon.sh --daemon --interval 30
+
+  # Show statistics
+  ./notification-daemon.sh --stats
+
+  # Stop daemon
+  ./notification-daemon.sh --stop
+
+Environment variables:
+  MISSION_CONTROL_URL    Mission Control base URL (default: http://localhost:3005)
+
+Log files:
+  $LOG_DIR/notification-daemon-YYYY-MM-DD.log
+EOF
+}
+
+# Validate arguments
+validate_args() {
+    if ! [[ "$LIMIT" =~ ^[1-9][0-9]*$ ]]; then
+        log "ERROR" "Invalid limit: $LIMIT (must be positive integer)"
+        exit 1
+    fi
+    
+    if ! [[ "$INTERVAL" =~ ^[1-9][0-9]*$ ]]; then
+        log "ERROR" "Invalid interval: $INTERVAL (must be positive integer)"
+        exit 1
+    fi
+}
+
+# Main execution
+main() {
+    parse_args "$@"
+    validate_args
+    
+    if [[ "$DAEMON_MODE" == "true" ]]; then
+        run_daemon
+    else
+        # Single run mode
+        log "INFO" "Starting single notification delivery run"
+        
+        if ! check_mission_control; then
+            log "ERROR" "Aborting: Mission Control not accessible"
+            exit 1
+        fi
+        
+        if deliver_notifications; then
+            log "INFO" "Notification delivery completed successfully"
+            exit 0
+        else
+            log "ERROR" "Notification delivery failed"
+            exit 1
+        fi
+    fi
+}
+
+# Run main function
+main "$@"

src/app/api/activities/route.ts

@@ -0,0 +1,217 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getDatabase, Activity } from '@/lib/db';
+
+/**
+ * GET /api/activities - Get activity stream or stats
+ * Query params: type, actor, entity_type, limit, offset, since, hours (for stats)
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams, pathname } = new URL(request.url);
+    
+    // Route to stats endpoint if requested
+    if (pathname.endsWith('/stats') || searchParams.has('stats')) {
+      return handleStatsRequest(request);
+    }
+    
+    // Default activities endpoint
+    return handleActivitiesRequest(request);
+  } catch (error) {
+    console.error('GET /api/activities error:', error);
+    return NextResponse.json({ error: 'Failed to process request' }, { status: 500 });
+  }
+}
+
+/**
+ * Handle regular activities request
+ */
+async function handleActivitiesRequest(request: NextRequest) {
+  try {
+    const db = getDatabase();
+    const { searchParams } = new URL(request.url);
+    
+    // Parse query parameters
+    const type = searchParams.get('type');
+    const actor = searchParams.get('actor');
+    const entity_type = searchParams.get('entity_type');
+    const limit = parseInt(searchParams.get('limit') || '50');
+    const offset = parseInt(searchParams.get('offset') || '0');
+    const since = searchParams.get('since'); // Unix timestamp for real-time updates
+    
+    // Build dynamic query
+    let query = 'SELECT * FROM activities WHERE 1=1';
+    const params: any[] = [];
+    
+    if (type) {
+      query += ' AND type = ?';
+      params.push(type);
+    }
+    
+    if (actor) {
+      query += ' AND actor = ?';
+      params.push(actor);
+    }
+    
+    if (entity_type) {
+      query += ' AND entity_type = ?';
+      params.push(entity_type);
+    }
+    
+    if (since) {
+      query += ' AND created_at > ?';
+      params.push(parseInt(since));
+    }
+    
+    query += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+    
+    const stmt = db.prepare(query);
+    const activities = stmt.all(...params) as Activity[];
+    
+    // Parse JSON data field and enhance with related entity data
+    const enhancedActivities = activities.map(activity => {
+      let entityDetails = null;
+      
+      try {
+        // Fetch related entity details based on entity_type
+        switch (activity.entity_type) {
+          case 'task':
+            const task = db.prepare('SELECT id, title, status FROM tasks WHERE id = ?').get(activity.entity_id) as any;
+            if (task) {
+              entityDetails = { type: 'task', ...task };
+            }
+            break;
+            
+          case 'agent':
+            const agent = db.prepare('SELECT id, name, role, status FROM agents WHERE id = ?').get(activity.entity_id) as any;
+            if (agent) {
+              entityDetails = { type: 'agent', ...agent };
+            }
+            break;
+            
+          case 'comment':
+            const comment = db.prepare(`
+              SELECT c.id, c.content, c.task_id, t.title as task_title 
+              FROM comments c 
+              LEFT JOIN tasks t ON c.task_id = t.id 
+              WHERE c.id = ?
+            `).get(activity.entity_id) as any;
+            if (comment) {
+              entityDetails = { 
+                type: 'comment', 
+                ...comment,
+                content_preview: comment.content?.substring(0, 100) || ''
+              };
+            }
+            break;
+        }
+      } catch (error) {
+        // If entity lookup fails, continue without entity details
+        console.warn(`Failed to fetch entity details for activity ${activity.id}:`, error);
+      }
+      
+      return {
+        ...activity,
+        data: activity.data ? JSON.parse(activity.data) : null,
+        entity: entityDetails
+      };
+    });
+    
+    // Get total count for pagination
+    let countQuery = 'SELECT COUNT(*) as total FROM activities WHERE 1=1';
+    const countParams: any[] = [];
+    
+    if (type) {
+      countQuery += ' AND type = ?';
+      countParams.push(type);
+    }
+    
+    if (actor) {
+      countQuery += ' AND actor = ?';
+      countParams.push(actor);
+    }
+    
+    if (entity_type) {
+      countQuery += ' AND entity_type = ?';
+      countParams.push(entity_type);
+    }
+    
+    if (since) {
+      countQuery += ' AND created_at > ?';
+      countParams.push(parseInt(since));
+    }
+    
+    const countResult = db.prepare(countQuery).get(...countParams) as { total: number };
+    
+    return NextResponse.json({ 
+      activities: enhancedActivities,
+      total: countResult.total,
+      hasMore: offset + activities.length < countResult.total
+    });
+  } catch (error) {
+    console.error('GET /api/activities (activities) error:', error);
+    return NextResponse.json({ error: 'Failed to fetch activities' }, { status: 500 });
+  }
+}
+
+/**
+ * Handle stats request
+ */
+async function handleStatsRequest(request: NextRequest) {
+  try {
+    const db = getDatabase();
+    const { searchParams } = new URL(request.url);
+    
+    // Parse timeframe parameter (defaults to 24 hours)
+    const hours = parseInt(searchParams.get('hours') || '24');
+    const since = Math.floor(Date.now() / 1000) - (hours * 3600);
+    
+    // Get activity counts by type
+    const activityStats = db.prepare(`
+      SELECT 
+        type,
+        COUNT(*) as count
+      FROM activities 
+      WHERE created_at > ?
+      GROUP BY type
+      ORDER BY count DESC
+    `).all(since) as { type: string; count: number }[];
+    
+    // Get most active actors
+    const activeActors = db.prepare(`
+      SELECT 
+        actor,
+        COUNT(*) as activity_count
+      FROM activities 
+      WHERE created_at > ?
+      GROUP BY actor
+      ORDER BY activity_count DESC
+      LIMIT 10
+    `).all(since) as { actor: string; activity_count: number }[];
+    
+    // Get activity timeline (hourly buckets)
+    const timeline = db.prepare(`
+      SELECT 
+        (created_at / 3600) * 3600 as hour_bucket,
+        COUNT(*) as count
+      FROM activities 
+      WHERE created_at > ?
+      GROUP BY hour_bucket
+      ORDER BY hour_bucket ASC
+    `).all(since) as { hour_bucket: number; count: number }[];
+    
+    return NextResponse.json({
+      timeframe: `${hours} hours`,
+      activityByType: activityStats,
+      topActors: activeActors,
+      timeline: timeline.map(item => ({
+        timestamp: item.hour_bucket,
+        count: item.count,
+        hour: new Date(item.hour_bucket * 1000).toISOString()
+      }))
+    });
+  } catch (error) {
+    console.error('GET /api/activities (stats) error:', error);
+    return NextResponse.json({ error: 'Failed to fetch activity stats' }, { status: 500 });
+  }
+}

src/app/api/agents/[id]/heartbeat/route.ts

@@ -0,0 +1,179 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getDatabase, db_helpers } from '@/lib/db';
+import { requireRole } from '@/lib/auth';
+
+/**
+ * GET /api/agents/[id]/heartbeat - Agent heartbeat check
+ * 
+ * Checks for:
+ * - @mentions in recent comments
+ * - Assigned tasks
+ * - Recent activity feed items
+ * 
+ * Returns work items or "HEARTBEAT_OK" if nothing to do
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const db = getDatabase();
+    const resolvedParams = await params;
+    const agentId = resolvedParams.id;
+    
+    // Get agent by ID or name
+    let agent;
+    if (isNaN(Number(agentId))) {
+      // Lookup by name
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId);
+    } else {
+      // Lookup by ID
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId));
+    }
+    
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+    }
+    
+    const workItems: any[] = [];
+    const now = Math.floor(Date.now() / 1000);
+    const fourHoursAgo = now - (4 * 60 * 60); // Check last 4 hours
+    
+    // 1. Check for @mentions in recent comments
+    const mentions = db.prepare(`
+      SELECT c.*, t.title as task_title 
+      FROM comments c
+      JOIN tasks t ON c.task_id = t.id
+      WHERE c.mentions LIKE ?
+      AND c.created_at > ?
+      ORDER BY c.created_at DESC
+      LIMIT 10
+    `).all(`%"${agent.name}"%`, fourHoursAgo);
+    
+    if (mentions.length > 0) {
+      workItems.push({
+        type: 'mentions',
+        count: mentions.length,
+        items: mentions.map((m: any) => ({
+          id: m.id,
+          task_title: m.task_title,
+          author: m.author,
+          content: m.content.substring(0, 100) + '...',
+          created_at: m.created_at
+        }))
+      });
+    }
+    
+    // 2. Check for assigned tasks
+    const assignedTasks = db.prepare(`
+      SELECT * FROM tasks 
+      WHERE assigned_to = ?
+      AND status IN ('assigned', 'in_progress')
+      ORDER BY priority DESC, created_at ASC
+      LIMIT 10
+    `).all(agent.name);
+    
+    if (assignedTasks.length > 0) {
+      workItems.push({
+        type: 'assigned_tasks',
+        count: assignedTasks.length,
+        items: assignedTasks.map((t: any) => ({
+          id: t.id,
+          title: t.title,
+          status: t.status,
+          priority: t.priority,
+          due_date: t.due_date
+        }))
+      });
+    }
+    
+    // 3. Check for unread notifications
+    const notifications = db_helpers.getUnreadNotifications(agent.name);
+    
+    if (notifications.length > 0) {
+      workItems.push({
+        type: 'notifications',
+        count: notifications.length,
+        items: notifications.slice(0, 5).map(n => ({
+          id: n.id,
+          type: n.type,
+          title: n.title,
+          message: n.message,
+          created_at: n.created_at
+        }))
+      });
+    }
+    
+    // 4. Check for urgent activities that might need attention
+    const urgentActivities = db.prepare(`
+      SELECT * FROM activities 
+      WHERE type IN ('task_created', 'task_assigned', 'high_priority_alert')
+      AND created_at > ?
+      AND description LIKE ?
+      ORDER BY created_at DESC
+      LIMIT 5
+    `).all(fourHoursAgo, `%${agent.name}%`);
+    
+    if (urgentActivities.length > 0) {
+      workItems.push({
+        type: 'urgent_activities',
+        count: urgentActivities.length,
+        items: urgentActivities.map((a: any) => ({
+          id: a.id,
+          type: a.type,
+          description: a.description,
+          created_at: a.created_at
+        }))
+      });
+    }
+    
+    // Update agent last_seen and status to show heartbeat activity
+    db_helpers.updateAgentStatus(agent.name, 'idle', 'Heartbeat check');
+    
+    // Log heartbeat activity
+    db_helpers.logActivity(
+      'agent_heartbeat',
+      'agent',
+      agent.id,
+      agent.name,
+      `Heartbeat check completed - ${workItems.length > 0 ? `${workItems.length} work items found` : 'no work items'}`,
+      { workItemsCount: workItems.length, workItemTypes: workItems.map(w => w.type) }
+    );
+    
+    if (workItems.length === 0) {
+      return NextResponse.json({
+        status: 'HEARTBEAT_OK',
+        agent: agent.name,
+        checked_at: now,
+        message: 'No work items found'
+      });
+    }
+    
+    return NextResponse.json({
+      status: 'WORK_ITEMS_FOUND',
+      agent: agent.name,
+      checked_at: now,
+      work_items: workItems,
+      total_items: workItems.reduce((sum, item) => sum + item.count, 0)
+    });
+    
+  } catch (error) {
+    console.error('GET /api/agents/[id]/heartbeat error:', error);
+    return NextResponse.json({ error: 'Failed to perform heartbeat check' }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/agents/[id]/heartbeat - Manual heartbeat trigger
+ * Allows manual heartbeat checks from UI or scripts
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  // Reuse GET logic for manual triggers
+  return GET(request, { params });
+}

src/app/api/agents/[id]/memory/route.ts

@@ -0,0 +1,213 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getDatabase, db_helpers } from '@/lib/db';
+import { requireRole } from '@/lib/auth';
+
+/**
+ * GET /api/agents/[id]/memory - Get agent's working memory
+ * 
+ * Working memory is stored as WORKING.md content in the database
+ * Each agent has their own working memory space for temporary notes
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'viewer');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  try {
+    const db = getDatabase();
+    const resolvedParams = await params;
+    const agentId = resolvedParams.id;
+    
+    // Get agent by ID or name
+    let agent;
+    if (isNaN(Number(agentId))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId);
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId));
+    }
+    
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+    }
+    
+    // Check if agent has a working_memory column, if not create it
+    const columns = db.prepare("PRAGMA table_info(agents)").all();
+    const hasWorkingMemory = columns.some((col: any) => col.name === 'working_memory');
+    
+    if (!hasWorkingMemory) {
+      // Add working_memory column to agents table
+      db.exec("ALTER TABLE agents ADD COLUMN working_memory TEXT DEFAULT ''");
+    }
+    
+    // Get working memory content
+    const memoryStmt = db.prepare(`SELECT working_memory FROM agents WHERE ${isNaN(Number(agentId)) ? 'name' : 'id'} = ?`);
+    const result = memoryStmt.get(agentId) as any;
+    
+    const workingMemory = result?.working_memory || '';
+    
+    return NextResponse.json({
+      agent: {
+        id: agent.id,
+        name: agent.name,
+        role: agent.role
+      },
+      working_memory: workingMemory,
+      updated_at: agent.updated_at,
+      size: workingMemory.length
+    });
+  } catch (error) {
+    console.error('GET /api/agents/[id]/memory error:', error);
+    return NextResponse.json({ error: 'Failed to fetch working memory' }, { status: 500 });
+  }
+}
+
+/**
+ * PUT /api/agents/[id]/memory - Update agent's working memory
+ */
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  try {
+    const db = getDatabase();
+    const resolvedParams = await params;
+    const agentId = resolvedParams.id;
+    const body = await request.json();
+    const { working_memory, append } = body;
+    
+    // Get agent by ID or name
+    let agent;
+    if (isNaN(Number(agentId))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId);
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId));
+    }
+    
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+    }
+    
+    // Check if agent has a working_memory column, if not create it
+    const columns = db.prepare("PRAGMA table_info(agents)").all();
+    const hasWorkingMemory = columns.some((col: any) => col.name === 'working_memory');
+    
+    if (!hasWorkingMemory) {
+      db.exec("ALTER TABLE agents ADD COLUMN working_memory TEXT DEFAULT ''");
+    }
+    
+    let newContent = working_memory || '';
+    
+    // Handle append mode
+    if (append) {
+      const currentStmt = db.prepare(`SELECT working_memory FROM agents WHERE ${isNaN(Number(agentId)) ? 'name' : 'id'} = ?`);
+      const current = currentStmt.get(agentId) as any;
+      const currentContent = current?.working_memory || '';
+      
+      // Add timestamp and append
+      const timestamp = new Date().toISOString();
+      newContent = currentContent + (currentContent ? '\n\n' : '') + 
+                   `## ${timestamp}\n${working_memory}`;
+    }
+    
+    const now = Math.floor(Date.now() / 1000);
+    
+    // Update working memory
+    const updateStmt = db.prepare(`
+      UPDATE agents 
+      SET working_memory = ?, updated_at = ?
+      WHERE ${isNaN(Number(agentId)) ? 'name' : 'id'} = ?
+    `);
+    
+    updateStmt.run(newContent, now, agentId);
+    
+    // Log activity
+    db_helpers.logActivity(
+      'agent_memory_updated',
+      'agent',
+      agent.id,
+      agent.name,
+      `Working memory ${append ? 'appended' : 'updated'} for agent ${agent.name}`,
+      { 
+        content_length: newContent.length,
+        append_mode: append || false,
+        timestamp: now
+      }
+    );
+    
+    return NextResponse.json({
+      success: true,
+      message: `Working memory ${append ? 'appended' : 'updated'} for ${agent.name}`,
+      working_memory: newContent,
+      updated_at: now,
+      size: newContent.length
+    });
+  } catch (error) {
+    console.error('PUT /api/agents/[id]/memory error:', error);
+    return NextResponse.json({ error: 'Failed to update working memory' }, { status: 500 });
+  }
+}
+
+/**
+ * DELETE /api/agents/[id]/memory - Clear agent's working memory
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  try {
+    const db = getDatabase();
+    const resolvedParams = await params;
+    const agentId = resolvedParams.id;
+
+    // Get agent by ID or name
+    let agent;
+    if (isNaN(Number(agentId))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId);
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId));
+    }
+    
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+    }
+    
+    const now = Math.floor(Date.now() / 1000);
+    
+    // Clear working memory
+    const updateStmt = db.prepare(`
+      UPDATE agents 
+      SET working_memory = '', updated_at = ?
+      WHERE ${isNaN(Number(agentId)) ? 'name' : 'id'} = ?
+    `);
+    
+    updateStmt.run(now, agentId);
+    
+    // Log activity
+    db_helpers.logActivity(
+      'agent_memory_cleared',
+      'agent',
+      agent.id,
+      agent.name,
+      `Working memory cleared for agent ${agent.name}`,
+      { timestamp: now }
+    );
+    
+    return NextResponse.json({
+      success: true,
+      message: `Working memory cleared for ${agent.name}`,
+      working_memory: '',
+      updated_at: now
+    });
+  } catch (error) {
+    console.error('DELETE /api/agents/[id]/memory error:', error);
+    return NextResponse.json({ error: 'Failed to clear working memory' }, { status: 500 });
+  }
+}

src/app/api/agents/[id]/route.ts

@@ -0,0 +1,206 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getDatabase, db_helpers, logAuditEvent } from '@/lib/db'
+import { getUserFromRequest, requireRole } from '@/lib/auth'
+import { writeAgentToConfig } from '@/lib/agent-sync'
+import { eventBus } from '@/lib/event-bus'
+
+/**
+ * GET /api/agents/[id] - Get a single agent by ID or name
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const db = getDatabase()
+    const { id } = await params
+
+    let agent
+    if (isNaN(Number(id))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(id)
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(id))
+    }
+
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
+    }
+
+    const parsed = {
+      ...(agent as any),
+      config: (agent as any).config ? JSON.parse((agent as any).config) : {},
+    }
+
+    return NextResponse.json({ agent: parsed })
+  } catch (error) {
+    console.error('GET /api/agents/[id] error:', error)
+    return NextResponse.json({ error: 'Failed to fetch agent' }, { status: 500 })
+  }
+}
+
+/**
+ * PUT /api/agents/[id] - Update agent config with optional gateway write-back
+ *
+ * Body: {
+ *   role?: string
+ *   gateway_config?: object   - OpenClaw agent config fields to update
+ *   write_to_gateway?: boolean - If true, also write to openclaw.json
+ * }
+ */
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const db = getDatabase()
+    const { id } = await params
+    const body = await request.json()
+    const { role, gateway_config, write_to_gateway } = body
+
+    let agent
+    if (isNaN(Number(id))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(id) as any
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(id)) as any
+    }
+
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
+    }
+
+    const now = Math.floor(Date.now() / 1000)
+    const existingConfig = agent.config ? JSON.parse(agent.config) : {}
+
+    // Merge gateway_config into existing config
+    let newConfig = existingConfig
+    if (gateway_config && typeof gateway_config === 'object') {
+      newConfig = { ...existingConfig, ...gateway_config }
+    }
+
+    // Build update
+    const fields: string[] = ['updated_at = ?']
+    const values: any[] = [now]
+
+    if (role !== undefined) {
+      fields.push('role = ?')
+      values.push(role)
+    }
+
+    if (gateway_config) {
+      fields.push('config = ?')
+      values.push(JSON.stringify(newConfig))
+    }
+
+    values.push(agent.id)
+    db.prepare(`UPDATE agents SET ${fields.join(', ')} WHERE id = ?`).run(...values)
+
+    // Write back to openclaw.json if requested
+    if (write_to_gateway && gateway_config) {
+      try {
+        const openclawId = existingConfig.openclawId || agent.name.toLowerCase().replace(/\s+/g, '-')
+
+        // Build the config to write back (full OpenClaw format)
+        const writeBack: any = { id: openclawId }
+        if (gateway_config.model) writeBack.model = gateway_config.model
+        if (gateway_config.identity) writeBack.identity = gateway_config.identity
+        if (gateway_config.sandbox) writeBack.sandbox = gateway_config.sandbox
+        if (gateway_config.tools) writeBack.tools = gateway_config.tools
+        if (gateway_config.subagents) writeBack.subagents = gateway_config.subagents
+        if (gateway_config.memorySearch) writeBack.memorySearch = gateway_config.memorySearch
+
+        await writeAgentToConfig(writeBack)
+
+        const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+        logAuditEvent({
+          action: 'agent_config_writeback',
+          actor: auth.user.username,
+          actor_id: auth.user.id,
+          target_type: 'agent',
+          target_id: agent.id,
+          detail: { agent_name: agent.name, openclaw_id: openclawId, fields: Object.keys(gateway_config) },
+          ip_address: ipAddress,
+        })
+      } catch (err: any) {
+        // Config update succeeded in DB but gateway write failed
+        return NextResponse.json({
+          warning: `Agent updated in MC but gateway write failed: ${err.message}`,
+          agent: { ...agent, config: newConfig, role: role || agent.role, updated_at: now },
+        })
+      }
+    }
+
+    // Log activity
+    db_helpers.logActivity(
+      'agent_config_updated',
+      'agent',
+      agent.id,
+      auth.user.username,
+      `Config updated for agent ${agent.name}${write_to_gateway ? ' (+ gateway)' : ''}`,
+      { fields: Object.keys(gateway_config || {}), write_to_gateway }
+    )
+
+    // Broadcast update
+    eventBus.broadcast('agent.updated', {
+      id: agent.id,
+      name: agent.name,
+      config: newConfig,
+      updated_at: now,
+    })
+
+    return NextResponse.json({
+      success: true,
+      agent: { ...agent, config: newConfig, role: role || agent.role, updated_at: now },
+    })
+  } catch (error: any) {
+    console.error('PUT /api/agents/[id] error:', error)
+    return NextResponse.json({ error: error.message || 'Failed to update agent' }, { status: 500 })
+  }
+}
+
+/**
+ * DELETE /api/agents/[id] - Delete an agent
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const db = getDatabase()
+    const { id } = await params
+
+    let agent
+    if (isNaN(Number(id))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(id) as any
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(id)) as any
+    }
+
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
+    }
+
+    db.prepare('DELETE FROM agents WHERE id = ?').run(agent.id)
+
+    db_helpers.logActivity(
+      'agent_deleted',
+      'agent',
+      agent.id,
+      auth.user.username,
+      `Deleted agent: ${agent.name}`,
+      { name: agent.name, role: agent.role }
+    )
+
+    eventBus.broadcast('agent.deleted', { id: agent.id, name: agent.name })
+
+    return NextResponse.json({ success: true, deleted: agent.name })
+  } catch (error) {
+    console.error('DELETE /api/agents/[id] error:', error)
+    return NextResponse.json({ error: 'Failed to delete agent' }, { status: 500 })
+  }
+}

src/app/api/agents/[id]/soul/route.ts

@@ -0,0 +1,229 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getDatabase, db_helpers } from '@/lib/db';
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { config } from '@/lib/config';
+import { resolveWithin } from '@/lib/paths';
+import { getUserFromRequest, requireRole } from '@/lib/auth';
+
+/**
+ * GET /api/agents/[id]/soul - Get agent's SOUL content
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const db = getDatabase();
+    const resolvedParams = await params;
+    const agentId = resolvedParams.id;
+    
+    // Get agent by ID or name
+    let agent;
+    if (isNaN(Number(agentId))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId);
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId));
+    }
+    
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+    }
+    
+    const templatesPath = config.soulTemplatesDir;
+    let availableTemplates: string[] = [];
+    
+    try {
+      if (templatesPath && existsSync(templatesPath)) {
+        const files = readdirSync(templatesPath);
+        availableTemplates = files
+          .filter(file => file.endsWith('.md'))
+          .map(file => file.replace('.md', ''));
+      }
+    } catch (error) {
+      console.warn('Could not read soul templates directory:', error);
+    }
+    
+    return NextResponse.json({
+      agent: {
+        id: agent.id,
+        name: agent.name,
+        role: agent.role
+      },
+      soul_content: agent.soul_content || '',
+      available_templates: availableTemplates,
+      updated_at: agent.updated_at
+    });
+  } catch (error) {
+    console.error('GET /api/agents/[id]/soul error:', error);
+    return NextResponse.json({ error: 'Failed to fetch SOUL content' }, { status: 500 });
+  }
+}
+
+/**
+ * PUT /api/agents/[id]/soul - Update agent's SOUL content
+ */
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  try {
+    const db = getDatabase();
+    const resolvedParams = await params;
+    const agentId = resolvedParams.id;
+    const body = await request.json();
+    const { soul_content, template_name } = body;
+    
+    // Get agent by ID or name
+    let agent;
+    if (isNaN(Number(agentId))) {
+      agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId);
+    } else {
+      agent = db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId));
+    }
+    
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+    }
+    
+    let newSoulContent = soul_content;
+    
+    // If template_name is provided, load from template
+    if (template_name) {
+      if (!config.soulTemplatesDir) {
+        return NextResponse.json({ error: 'Templates directory not configured' }, { status: 500 });
+      }
+      let templatePath: string;
+      try {
+        templatePath = resolveWithin(config.soulTemplatesDir, `${template_name}.md`);
+      } catch (pathError) {
+        return NextResponse.json({ error: 'Invalid template name' }, { status: 400 });
+      }
+      
+      try {
+        if (existsSync(templatePath)) {
+          const templateContent = readFileSync(templatePath, 'utf8');
+          // Replace placeholders with agent info
+          newSoulContent = templateContent
+            .replace(/{{AGENT_NAME}}/g, agent.name)
+            .replace(/{{AGENT_ROLE}}/g, agent.role)
+            .replace(/{{TIMESTAMP}}/g, new Date().toISOString());
+        } else {
+          return NextResponse.json({ error: 'Template not found' }, { status: 404 });
+        }
+      } catch (error) {
+        console.error('Error loading soul template:', error);
+        return NextResponse.json({ error: 'Failed to load template' }, { status: 500 });
+      }
+    }
+    
+    const now = Math.floor(Date.now() / 1000);
+    
+    // Update SOUL content
+    const updateStmt = db.prepare(`
+      UPDATE agents 
+      SET soul_content = ?, updated_at = ?
+      WHERE ${isNaN(Number(agentId)) ? 'name' : 'id'} = ?
+    `);
+    
+    updateStmt.run(newSoulContent, now, agentId);
+    
+    // Log activity
+    db_helpers.logActivity(
+      'agent_soul_updated',
+      'agent',
+      agent.id,
+      getUserFromRequest(request)?.username || 'system',
+      `SOUL content updated for agent ${agent.name}${template_name ? ` using template: ${template_name}` : ''}`,
+      { 
+        template_used: template_name || null,
+        content_length: newSoulContent ? newSoulContent.length : 0,
+        previous_content_length: agent.soul_content ? agent.soul_content.length : 0
+      }
+    );
+    
+    return NextResponse.json({
+      success: true,
+      message: `SOUL content updated for ${agent.name}`,
+      soul_content: newSoulContent,
+      updated_at: now
+    });
+  } catch (error) {
+    console.error('PUT /api/agents/[id]/soul error:', error);
+    return NextResponse.json({ error: 'Failed to update SOUL content' }, { status: 500 });
+  }
+}
+
+/**
+ * GET /api/agents/[id]/soul/templates - Get available SOUL templates
+ * Also handles loading specific template content
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const templateName = searchParams.get('template');
+    
+    const templatesPath = config.soulTemplatesDir;
+    
+    if (!templatesPath || !existsSync(templatesPath)) {
+      return NextResponse.json({
+        templates: [],
+        message: 'Templates directory not found'
+      });
+    }
+    
+    if (templateName) {
+      // Get specific template content
+      let templatePath: string;
+      try {
+        templatePath = resolveWithin(templatesPath, `${templateName}.md`);
+      } catch (pathError) {
+        return NextResponse.json({ error: 'Invalid template name' }, { status: 400 });
+      }
+      
+      if (!existsSync(templatePath)) {
+        return NextResponse.json({ error: 'Template not found' }, { status: 404 });
+      }
+      
+      const templateContent = readFileSync(templatePath, 'utf8');
+      
+      return NextResponse.json({
+        template_name: templateName,
+        content: templateContent
+      });
+    }
+    
+    // List all available templates
+    const files = readdirSync(templatesPath);
+    const templates = files
+      .filter(file => file.endsWith('.md'))
+      .map(file => {
+        const name = file.replace('.md', '');
+        const templatePath = join(templatesPath, file);
+        const content = readFileSync(templatePath, 'utf8');
+        
+        // Extract first line as description
+        const firstLine = content.split('\n')[0];
+        const description = firstLine.startsWith('#') 
+          ? firstLine.replace(/^#+\s*/, '') 
+          : `${name} template`;
+        
+        return {
+          name,
+          description,
+          size: content.length
+        };
+      });
+    
+    return NextResponse.json({ templates });
+  } catch (error) {
+    console.error('PATCH /api/agents/[id]/soul error:', error);
+    return NextResponse.json({ error: 'Failed to fetch templates' }, { status: 500 });
+  }
+}

src/app/api/agents/[id]/wake/route.ts

@@ -0,0 +1,63 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getDatabase, db_helpers } from '@/lib/db'
+import { runOpenClaw } from '@/lib/command'
+import { requireRole } from '@/lib/auth'
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const resolvedParams = await params
+    const agentId = resolvedParams.id
+    const body = await request.json().catch(() => ({}))
+    const customMessage =
+      typeof body?.message === 'string' ? body.message.trim() : ''
+
+    const db = getDatabase()
+    const agent: any = isNaN(Number(agentId))
+      ? db.prepare('SELECT * FROM agents WHERE name = ?').get(agentId)
+      : db.prepare('SELECT * FROM agents WHERE id = ?').get(Number(agentId))
+
+    if (!agent) {
+      return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
+    }
+
+    if (!agent.session_key) {
+      return NextResponse.json(
+        { error: 'Agent has no session key configured' },
+        { status: 400 }
+      )
+    }
+
+    const message =
+      customMessage ||
+      `Wake up check-in for ${agent.name}. Please review assigned tasks and notifications.`
+
+    const { stdout, stderr } = await runOpenClaw(
+      ['gateway', 'sessions_send', '--session', agent.session_key, '--message', message],
+      { timeoutMs: 10000 }
+    )
+
+    if (stderr && stderr.includes('error')) {
+      return NextResponse.json(
+        { error: stderr.trim() || 'Failed to wake agent' },
+        { status: 500 }
+      )
+    }
+
+    db_helpers.updateAgentStatus(agent.name, 'idle', 'Manual wake')
+
+    return NextResponse.json({
+      success: true,
+      session_key: agent.session_key,
+      stdout: stdout.trim()
+    })
+  } catch (error) {
+    console.error('POST /api/agents/[id]/wake error:', error)
+    return NextResponse.json({ error: 'Failed to wake agent' }, { status: 500 })
+  }
+}

src/app/api/agents/comms/route.ts

@@ -0,0 +1,155 @@
+import { NextRequest, NextResponse } from "next/server"
+import { getDatabase, Message } from "@/lib/db"
+
+/**
+ * GET /api/agents/comms - Inter-agent communication stats and timeline
+ * Query params: limit, offset, since, agent
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const db = getDatabase()
+    const { searchParams } = new URL(request.url)
+
+    const limit = parseInt(searchParams.get("limit") || "100")
+    const offset = parseInt(searchParams.get("offset") || "0")
+    const since = searchParams.get("since")
+    const agent = searchParams.get("agent")
+
+    // Filter out human/system messages - only agent-to-agent
+    const humanNames = ["human", "system", "operator"]
+    const humanPlaceholders = humanNames.map(() => "?").join(",")
+
+    // 1. Get inter-agent messages
+    let messagesQuery = `
+      SELECT * FROM messages
+      WHERE to_agent IS NOT NULL
+        AND from_agent NOT IN (${humanPlaceholders})
+        AND to_agent NOT IN (${humanPlaceholders})
+    `
+    const messagesParams: any[] = [...humanNames, ...humanNames]
+
+    if (since) {
+      messagesQuery += " AND created_at > ?"
+      messagesParams.push(parseInt(since))
+    }
+    if (agent) {
+      messagesQuery += " AND (from_agent = ? OR to_agent = ?)"
+      messagesParams.push(agent, agent)
+    }
+
+    // Deterministic chronological ordering prevents visual jumps in UI
+    messagesQuery += " ORDER BY created_at ASC, id ASC LIMIT ? OFFSET ?"
+    messagesParams.push(limit, offset)
+
+    const messages = db.prepare(messagesQuery).all(...messagesParams) as Message[]
+
+    // 2. Communication graph edges
+    let graphQuery = `
+      SELECT
+        from_agent, to_agent,
+        COUNT(*) as message_count,
+        MAX(created_at) as last_message_at
+      FROM messages
+      WHERE to_agent IS NOT NULL
+        AND from_agent NOT IN (${humanPlaceholders})
+        AND to_agent NOT IN (${humanPlaceholders})
+    `
+    const graphParams: any[] = [...humanNames, ...humanNames]
+    if (since) {
+      graphQuery += " AND created_at > ?"
+      graphParams.push(parseInt(since))
+    }
+    graphQuery += " GROUP BY from_agent, to_agent ORDER BY message_count DESC"
+
+    const edges = db.prepare(graphQuery).all(...graphParams)
+
+    // 3. Per-agent sent/received stats
+    const statsQuery = `
+      SELECT agent, SUM(sent) as sent, SUM(received) as received FROM (
+        SELECT from_agent as agent, COUNT(*) as sent, 0 as received
+        FROM messages WHERE to_agent IS NOT NULL
+          AND from_agent NOT IN (${humanPlaceholders})
+          AND to_agent NOT IN (${humanPlaceholders})
+        GROUP BY from_agent
+        UNION ALL
+        SELECT to_agent as agent, 0 as sent, COUNT(*) as received
+        FROM messages WHERE to_agent IS NOT NULL
+          AND from_agent NOT IN (${humanPlaceholders})
+          AND to_agent NOT IN (${humanPlaceholders})
+        GROUP BY to_agent
+      ) GROUP BY agent ORDER BY (sent + received) DESC
+    `
+    const statsParams = [...humanNames, ...humanNames, ...humanNames, ...humanNames]
+    const agentStats = db.prepare(statsQuery).all(...statsParams)
+
+    // 4. Total count
+    let countQuery = `
+      SELECT COUNT(*) as total FROM messages
+      WHERE to_agent IS NOT NULL
+        AND from_agent NOT IN (${humanPlaceholders})
+        AND to_agent NOT IN (${humanPlaceholders})
+    `
+    const countParams: any[] = [...humanNames, ...humanNames]
+    if (since) {
+      countQuery += " AND created_at > ?"
+      countParams.push(parseInt(since))
+    }
+    if (agent) {
+      countQuery += " AND (from_agent = ? OR to_agent = ?)"
+      countParams.push(agent, agent)
+    }
+    const { total } = db.prepare(countQuery).get(...countParams) as { total: number }
+
+    let seededCountQuery = `
+      SELECT COUNT(*) as seeded FROM messages
+      WHERE to_agent IS NOT NULL
+        AND from_agent NOT IN (${humanPlaceholders})
+        AND to_agent NOT IN (${humanPlaceholders})
+        AND conversation_id LIKE ?
+    `
+    const seededParams: any[] = [...humanNames, ...humanNames, "conv-multi-%"]
+    if (since) {
+      seededCountQuery += " AND created_at > ?"
+      seededParams.push(parseInt(since))
+    }
+    if (agent) {
+      seededCountQuery += " AND (from_agent = ? OR to_agent = ?)"
+      seededParams.push(agent, agent)
+    }
+    const { seeded } = db.prepare(seededCountQuery).get(...seededParams) as { seeded: number }
+
+    const seededCount = seeded || 0
+    const liveCount = Math.max(0, total - seededCount)
+    const source =
+      total === 0 ? "empty" :
+      liveCount === 0 ? "seeded" :
+      seededCount === 0 ? "live" :
+      "mixed"
+
+    const parsed = messages.map((msg) => {
+      let parsedMetadata: any = null
+      if (msg.metadata) {
+        try {
+          parsedMetadata = JSON.parse(msg.metadata)
+        } catch {
+          // Keep endpoint resilient even if one legacy row has bad metadata
+          parsedMetadata = null
+        }
+      }
+      return {
+        ...msg,
+        metadata: parsedMetadata,
+      }
+    })
+
+    return NextResponse.json({
+      messages: parsed,
+      total,
+      graph: { edges, agentStats },
+      source: { mode: source, seededCount, liveCount },
+    })
+  } catch (error) {
+    console.error("GET /api/agents/comms error:", error)
+    return NextResponse.json({ error: "Failed to fetch agent communications" }, { status: 500 })
+  }
+}

src/app/api/agents/message/route.ts

@@ -0,0 +1,70 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getDatabase, db_helpers } from '@/lib/db'
+import { runOpenClaw } from '@/lib/command'
+import { requireRole } from '@/lib/auth'
+
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const body = await request.json()
+    const from = (body.from || 'system') as string
+    const to = (body.to || '').trim()
+    const message = (body.message || '').trim()
+
+    if (!to || !message) {
+      return NextResponse.json(
+        { error: 'Both "to" and "message" are required' },
+        { status: 400 }
+      )
+    }
+
+    const db = getDatabase()
+    const agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(to) as any
+    if (!agent) {
+      return NextResponse.json({ error: 'Recipient agent not found' }, { status: 404 })
+    }
+    if (!agent.session_key) {
+      return NextResponse.json(
+        { error: 'Recipient agent has no session key configured' },
+        { status: 400 }
+      )
+    }
+
+    await runOpenClaw(
+      [
+        'gateway',
+        'sessions_send',
+        '--session',
+        agent.session_key,
+        '--message',
+        `Message from ${from}: ${message}`
+      ],
+      { timeoutMs: 10000 }
+    )
+
+    db_helpers.createNotification(
+      to,
+      'message',
+      'Direct Message',
+      `${from}: ${message.substring(0, 200)}${message.length > 200 ? '...' : ''}`,
+      'agent',
+      agent.id
+    )
+
+    db_helpers.logActivity(
+      'agent_message',
+      'agent',
+      agent.id,
+      from,
+      `Sent message to ${to}`,
+      { to }
+    )
+
+    return NextResponse.json({ success: true })
+  } catch (error) {
+    console.error('POST /api/agents/message error:', error)
+    return NextResponse.json({ error: 'Failed to send message' }, { status: 500 })
+  }
+}

src/app/api/agents/route.ts

@@ -0,0 +1,331 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getDatabase, Agent, db_helpers } from '@/lib/db';
+import { eventBus } from '@/lib/event-bus';
+import { getTemplate, buildAgentConfig } from '@/lib/agent-templates';
+import { writeAgentToConfig } from '@/lib/agent-sync';
+import { logAuditEvent } from '@/lib/db';
+import { getUserFromRequest, requireRole } from '@/lib/auth';
+
+/**
+ * GET /api/agents - List all agents with optional filtering
+ * Query params: status, role, limit, offset
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const db = getDatabase();
+    const { searchParams } = new URL(request.url);
+    
+    // Parse query parameters
+    const status = searchParams.get('status');
+    const role = searchParams.get('role');
+    const limit = parseInt(searchParams.get('limit') || '50');
+    const offset = parseInt(searchParams.get('offset') || '0');
+    
+    // Build dynamic query
+    let query = 'SELECT * FROM agents WHERE 1=1';
+    const params: any[] = [];
+    
+    if (status) {
+      query += ' AND status = ?';
+      params.push(status);
+    }
+    
+    if (role) {
+      query += ' AND role = ?';
+      params.push(role);
+    }
+    
+    query += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+    
+    const stmt = db.prepare(query);
+    const agents = stmt.all(...params) as Agent[];
+    
+    // Parse JSON config field
+    const agentsWithParsedData = agents.map(agent => ({
+      ...agent,
+      config: agent.config ? JSON.parse(agent.config) : {}
+    }));
+    
+    // Get task counts for each agent
+    const agentsWithStats = agentsWithParsedData.map(agent => {
+      const taskCountStmt = db.prepare(`
+        SELECT 
+          COUNT(*) as total,
+          SUM(CASE WHEN status = 'assigned' THEN 1 ELSE 0 END) as assigned,
+          SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END) as in_progress,
+          SUM(CASE WHEN status = 'done' THEN 1 ELSE 0 END) as completed
+        FROM tasks 
+        WHERE assigned_to = ?
+      `);
+      
+      const taskStats = taskCountStmt.get(agent.name) as any;
+      
+      return {
+        ...agent,
+        taskStats: {
+          total: taskStats.total || 0,
+          assigned: taskStats.assigned || 0,
+          in_progress: taskStats.in_progress || 0,
+          completed: taskStats.completed || 0
+        }
+      };
+    });
+    
+    return NextResponse.json({ 
+      agents: agentsWithStats, 
+      total: agents.length 
+    });
+  } catch (error) {
+    console.error('GET /api/agents error:', error);
+    return NextResponse.json({ error: 'Failed to fetch agents' }, { status: 500 });
+  }
+}
+
+/**
+ * POST /api/agents - Create a new agent
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'operator');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  try {
+    const db = getDatabase();
+    const body = await request.json();
+
+    const {
+      name,
+      role,
+      session_key,
+      soul_content,
+      status = 'offline',
+      config = {},
+      template,
+      gateway_config,
+      write_to_gateway
+    } = body;
+
+    // Resolve template if specified
+    let finalRole = role;
+    let finalConfig = config;
+    if (template) {
+      const tpl = getTemplate(template);
+      if (tpl) {
+        const builtConfig = buildAgentConfig(tpl, gateway_config || {});
+        finalConfig = { ...builtConfig, ...config };
+        if (!finalRole) finalRole = tpl.config.identity?.theme || tpl.type;
+      }
+    } else if (gateway_config) {
+      finalConfig = { ...config, ...gateway_config };
+    }
+
+    if (!name || !finalRole) {
+      return NextResponse.json({ error: 'Name and role are required' }, { status: 400 });
+    }
+
+    // Check if agent name already exists
+    const existingAgent = db.prepare('SELECT id FROM agents WHERE name = ?').get(name);
+    if (existingAgent) {
+      return NextResponse.json({ error: 'Agent name already exists' }, { status: 409 });
+    }
+    
+    const now = Math.floor(Date.now() / 1000);
+    
+    const stmt = db.prepare(`
+      INSERT INTO agents (
+        name, role, session_key, soul_content, status, 
+        created_at, updated_at, config
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    const result = stmt.run(
+      name,
+      finalRole,
+      session_key,
+      soul_content,
+      status,
+      now,
+      now,
+      JSON.stringify(finalConfig)
+    );
+    
+    const agentId = result.lastInsertRowid as number;
+    
+    // Log activity
+    db_helpers.logActivity(
+      'agent_created',
+      'agent',
+      agentId,
+      getUserFromRequest(request)?.username || 'system',
+      `Created agent: ${name} (${finalRole})${template ? ` from template: ${template}` : ''}`,
+      {
+        name,
+        role: finalRole,
+        status,
+        session_key,
+        template: template || null
+      }
+    );
+    
+    // Fetch the created agent
+    const createdAgent = db.prepare('SELECT * FROM agents WHERE id = ?').get(agentId) as Agent;
+    const parsedAgent = {
+      ...createdAgent,
+      config: JSON.parse(createdAgent.config || '{}'),
+      taskStats: { total: 0, assigned: 0, in_progress: 0, completed: 0 }
+    };
+
+    // Broadcast to SSE clients
+    eventBus.broadcast('agent.created', parsedAgent);
+
+    // Write to gateway config if requested
+    if (write_to_gateway && finalConfig) {
+      try {
+        const openclawId = (name || 'agent').toLowerCase().replace(/\s+/g, '-');
+        await writeAgentToConfig({
+          id: openclawId,
+          name,
+          ...(finalConfig.model && { model: finalConfig.model }),
+          ...(finalConfig.identity && { identity: finalConfig.identity }),
+          ...(finalConfig.sandbox && { sandbox: finalConfig.sandbox }),
+          ...(finalConfig.tools && { tools: finalConfig.tools }),
+          ...(finalConfig.subagents && { subagents: finalConfig.subagents }),
+          ...(finalConfig.memorySearch && { memorySearch: finalConfig.memorySearch }),
+        });
+
+        const ipAddress = request.headers.get('x-forwarded-for') || 'unknown';
+        logAuditEvent({
+          action: 'agent_gateway_create',
+          actor: getUserFromRequest(request)?.username || 'system',
+          target_type: 'agent',
+          target_id: agentId as number,
+          detail: { name, openclaw_id: openclawId, template: template || null },
+          ip_address: ipAddress,
+        });
+      } catch (gwErr: any) {
+        console.error('Gateway write-back failed:', gwErr);
+        return NextResponse.json({ 
+          agent: parsedAgent,
+          warning: `Agent created in MC but gateway write failed: ${gwErr.message}`
+        }, { status: 201 });
+      }
+    }
+
+    return NextResponse.json({ agent: parsedAgent }, { status: 201 });
+  } catch (error) {
+    console.error('POST /api/agents error:', error);
+    return NextResponse.json({ error: 'Failed to create agent' }, { status: 500 });
+  }
+}
+
+/**
+ * PUT /api/agents - Update agent status (bulk operation for status updates)
+ */
+export async function PUT(request: NextRequest) {
+  const auth = requireRole(request, 'operator');
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status });
+
+  try {
+    const db = getDatabase();
+    const body = await request.json();
+    
+    // Handle single agent update or bulk updates
+    if (body.name) {
+      // Single agent update
+      const { name, status, last_activity, config, session_key, soul_content, role } = body;
+      
+      const agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(name) as Agent;
+      if (!agent) {
+        return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+      }
+      
+      const now = Math.floor(Date.now() / 1000);
+      
+      // Build dynamic update query
+      const fieldsToUpdate = [];
+      const params: any[] = [];
+      
+      if (status !== undefined) {
+        fieldsToUpdate.push('status = ?');
+        params.push(status);
+        
+        fieldsToUpdate.push('last_seen = ?');
+        params.push(now);
+      }
+      
+      if (last_activity !== undefined) {
+        fieldsToUpdate.push('last_activity = ?');
+        params.push(last_activity);
+      }
+      
+      if (config !== undefined) {
+        fieldsToUpdate.push('config = ?');
+        params.push(JSON.stringify(config));
+      }
+      
+      if (session_key !== undefined) {
+        fieldsToUpdate.push('session_key = ?');
+        params.push(session_key);
+      }
+      
+      if (soul_content !== undefined) {
+        fieldsToUpdate.push('soul_content = ?');
+        params.push(soul_content);
+      }
+      
+      if (role !== undefined) {
+        fieldsToUpdate.push('role = ?');
+        params.push(role);
+      }
+      
+      fieldsToUpdate.push('updated_at = ?');
+      params.push(now);
+      params.push(name);
+      
+      if (fieldsToUpdate.length === 1) { // Only updated_at
+        return NextResponse.json({ error: 'No fields to update' }, { status: 400 });
+      }
+      
+      const stmt = db.prepare(`
+        UPDATE agents 
+        SET ${fieldsToUpdate.join(', ')}
+        WHERE name = ?
+      `);
+      
+      stmt.run(...params);
+      
+      // Log status change if status was updated
+      if (status !== undefined && status !== agent.status) {
+        db_helpers.logActivity(
+          'agent_status_change',
+          'agent',
+          agent.id,
+          name,
+          `Agent status changed from ${agent.status} to ${status}`,
+          {
+            oldStatus: agent.status,
+            newStatus: status,
+            last_activity
+          }
+        );
+      }
+
+      // Broadcast update to SSE clients
+      eventBus.broadcast('agent.updated', {
+        id: agent.id,
+        name,
+        ...(status !== undefined && { status }),
+        ...(last_activity !== undefined && { last_activity }),
+        ...(role !== undefined && { role }),
+        updated_at: now,
+      });
+
+      return NextResponse.json({ success: true });
+    } else {
+      return NextResponse.json({ error: 'Agent name is required' }, { status: 400 });
+    }
+  } catch (error) {
+    console.error('PUT /api/agents error:', error);
+    return NextResponse.json({ error: 'Failed to update agent' }, { status: 500 });
+  }
+}

src/app/api/agents/sync/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { syncAgentsFromConfig, previewSyncDiff } from '@/lib/agent-sync'
+
+/**
+ * POST /api/agents/sync - Trigger agent config sync from openclaw.json
+ * Requires admin role.
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const result = await syncAgentsFromConfig(auth.user.username)
+
+    if (result.error) {
+      return NextResponse.json({ error: result.error }, { status: 500 })
+    }
+
+    return NextResponse.json(result)
+  } catch (error: any) {
+    console.error('POST /api/agents/sync error:', error)
+    return NextResponse.json({ error: error.message || 'Sync failed' }, { status: 500 })
+  }
+}
+
+/**
+ * GET /api/agents/sync - Preview diff between openclaw.json and MC
+ * Shows what would change without writing.
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const diff = await previewSyncDiff()
+    return NextResponse.json(diff)
+  } catch (error: any) {
+    console.error('GET /api/agents/sync error:', error)
+    return NextResponse.json({ error: error.message || 'Preview failed' }, { status: 500 })
+  }
+}

src/app/api/alerts/route.ts

@@ -0,0 +1,311 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { getDatabase } from '@/lib/db'
+
+interface AlertRule {
+  id: number
+  name: string
+  description: string | null
+  enabled: number
+  entity_type: string
+  condition_field: string
+  condition_operator: string
+  condition_value: string
+  action_type: string
+  action_config: string
+  cooldown_minutes: number
+  last_triggered_at: number | null
+  trigger_count: number
+  created_by: string
+  created_at: number
+  updated_at: number
+}
+
+/**
+ * GET /api/alerts - List all alert rules
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'viewer')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const db = getDatabase()
+  try {
+    const rules = db.prepare('SELECT * FROM alert_rules ORDER BY created_at DESC').all() as AlertRule[]
+    return NextResponse.json({ rules })
+  } catch {
+    return NextResponse.json({ rules: [] })
+  }
+}
+
+/**
+ * POST /api/alerts - Create a new alert rule or evaluate rules
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const db = getDatabase()
+  const body = await request.json()
+
+  // Evaluate all enabled rules
+  if (body.action === 'evaluate') {
+    return evaluateRules(db)
+  }
+
+  // Create new rule
+  const { name, description, entity_type, condition_field, condition_operator, condition_value, action_type, action_config, cooldown_minutes } = body
+
+  if (!name || !entity_type || !condition_field || !condition_operator || !condition_value) {
+    return NextResponse.json({ error: 'Missing required fields: name, entity_type, condition_field, condition_operator, condition_value' }, { status: 400 })
+  }
+
+  const validEntities = ['agent', 'task', 'session', 'activity']
+  if (!validEntities.includes(entity_type)) {
+    return NextResponse.json({ error: `entity_type must be one of: ${validEntities.join(', ')}` }, { status: 400 })
+  }
+
+  const validOperators = ['equals', 'not_equals', 'greater_than', 'less_than', 'contains', 'count_above', 'count_below', 'age_minutes_above']
+  if (!validOperators.includes(condition_operator)) {
+    return NextResponse.json({ error: `condition_operator must be one of: ${validOperators.join(', ')}` }, { status: 400 })
+  }
+
+  try {
+    const result = db.prepare(`
+      INSERT INTO alert_rules (name, description, entity_type, condition_field, condition_operator, condition_value, action_type, action_config, cooldown_minutes, created_by)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      name,
+      description || null,
+      entity_type,
+      condition_field,
+      condition_operator,
+      condition_value,
+      action_type || 'notification',
+      JSON.stringify(action_config || {}),
+      cooldown_minutes || 60,
+      auth.user?.username || 'system'
+    )
+
+    // Audit log
+    try {
+      db.prepare('INSERT INTO audit_log (action, actor, detail) VALUES (?, ?, ?)').run(
+        'alert_rule_created',
+        auth.user?.username || 'system',
+        `Created alert rule: ${name}`
+      )
+    } catch { /* audit table might not exist */ }
+
+    const rule = db.prepare('SELECT * FROM alert_rules WHERE id = ?').get(result.lastInsertRowid) as AlertRule
+    return NextResponse.json({ rule }, { status: 201 })
+  } catch (err: any) {
+    return NextResponse.json({ error: err.message || 'Failed to create rule' }, { status: 500 })
+  }
+}
+
+/**
+ * PUT /api/alerts - Update an alert rule
+ */
+export async function PUT(request: NextRequest) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const db = getDatabase()
+  const body = await request.json()
+  const { id, ...updates } = body
+
+  if (!id) return NextResponse.json({ error: 'id is required' }, { status: 400 })
+
+  const existing = db.prepare('SELECT * FROM alert_rules WHERE id = ?').get(id) as AlertRule | undefined
+  if (!existing) return NextResponse.json({ error: 'Rule not found' }, { status: 404 })
+
+  const allowed = ['name', 'description', 'enabled', 'entity_type', 'condition_field', 'condition_operator', 'condition_value', 'action_type', 'action_config', 'cooldown_minutes']
+  const sets: string[] = []
+  const values: any[] = []
+
+  for (const key of allowed) {
+    if (key in updates) {
+      sets.push(`${key} = ?`)
+      values.push(key === 'action_config' ? JSON.stringify(updates[key]) : updates[key])
+    }
+  }
+
+  if (sets.length === 0) return NextResponse.json({ error: 'No valid fields to update' }, { status: 400 })
+
+  sets.push('updated_at = (unixepoch())')
+  values.push(id)
+
+  db.prepare(`UPDATE alert_rules SET ${sets.join(', ')} WHERE id = ?`).run(...values)
+
+  const updated = db.prepare('SELECT * FROM alert_rules WHERE id = ?').get(id) as AlertRule
+  return NextResponse.json({ rule: updated })
+}
+
+/**
+ * DELETE /api/alerts - Delete an alert rule
+ */
+export async function DELETE(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const db = getDatabase()
+  const body = await request.json()
+  const { id } = body
+
+  if (!id) return NextResponse.json({ error: 'id is required' }, { status: 400 })
+
+  const result = db.prepare('DELETE FROM alert_rules WHERE id = ?').run(id)
+
+  try {
+    db.prepare('INSERT INTO audit_log (action, actor, detail) VALUES (?, ?, ?)').run(
+      'alert_rule_deleted',
+      auth.user?.username || 'system',
+      `Deleted alert rule #${id}`
+    )
+  } catch { /* audit table might not exist */ }
+
+  return NextResponse.json({ deleted: result.changes > 0 })
+}
+
+/**
+ * Evaluate all enabled alert rules against current data
+ */
+function evaluateRules(db: ReturnType<typeof getDatabase>) {
+  let rules: AlertRule[]
+  try {
+    rules = db.prepare('SELECT * FROM alert_rules WHERE enabled = 1').all() as AlertRule[]
+  } catch {
+    return NextResponse.json({ evaluated: 0, triggered: 0, results: [] })
+  }
+
+  const now = Math.floor(Date.now() / 1000)
+  const results: { rule_id: number; rule_name: string; triggered: boolean; reason?: string }[] = []
+
+  for (const rule of rules) {
+    // Check cooldown
+    if (rule.last_triggered_at && (now - rule.last_triggered_at) < rule.cooldown_minutes * 60) {
+      results.push({ rule_id: rule.id, rule_name: rule.name, triggered: false, reason: 'In cooldown' })
+      continue
+    }
+
+    const triggered = evaluateRule(db, rule, now)
+    results.push({ rule_id: rule.id, rule_name: rule.name, triggered, reason: triggered ? 'Condition met' : 'Condition not met' })
+
+    if (triggered) {
+      // Update trigger tracking
+      db.prepare('UPDATE alert_rules SET last_triggered_at = ?, trigger_count = trigger_count + 1 WHERE id = ?').run(now, rule.id)
+
+      // Create notification
+      try {
+        const config = JSON.parse(rule.action_config || '{}')
+        const recipient = config.recipient || 'system'
+        db.prepare(`
+          INSERT INTO notifications (recipient, type, title, message, source_type, source_id)
+          VALUES (?, 'alert', ?, ?, 'alert_rule', ?)
+        `).run(recipient, `Alert: ${rule.name}`, rule.description || `Rule "${rule.name}" triggered`, rule.id)
+      } catch { /* notification creation failed */ }
+    }
+  }
+
+  const triggered = results.filter(r => r.triggered).length
+  return NextResponse.json({ evaluated: rules.length, triggered, results })
+}
+
+function evaluateRule(db: ReturnType<typeof getDatabase>, rule: AlertRule, now: number): boolean {
+  try {
+    switch (rule.entity_type) {
+      case 'agent': return evaluateAgentRule(db, rule, now)
+      case 'task': return evaluateTaskRule(db, rule, now)
+      case 'session': return evaluateSessionRule(db, rule, now)
+      case 'activity': return evaluateActivityRule(db, rule, now)
+      default: return false
+    }
+  } catch {
+    return false
+  }
+}
+
+function evaluateAgentRule(db: ReturnType<typeof getDatabase>, rule: AlertRule, now: number): boolean {
+  const { condition_field, condition_operator, condition_value } = rule
+
+  if (condition_operator === 'count_above' || condition_operator === 'count_below') {
+    const count = (db.prepare(`SELECT COUNT(*) as c FROM agents WHERE ${safeColumn('agents', condition_field)} = ?`).get(condition_value) as any)?.c || 0
+    return condition_operator === 'count_above' ? count > parseInt(condition_value) : count < parseInt(condition_value)
+  }
+
+  if (condition_operator === 'age_minutes_above') {
+    // Check agents where field value is older than N minutes (e.g., last_seen)
+    const threshold = now - parseInt(condition_value) * 60
+    const count = (db.prepare(`SELECT COUNT(*) as c FROM agents WHERE status != 'offline' AND ${safeColumn('agents', condition_field)} < ?`).get(threshold) as any)?.c || 0
+    return count > 0
+  }
+
+  const agents = db.prepare(`SELECT ${safeColumn('agents', condition_field)} as val FROM agents WHERE status != 'offline'`).all() as any[]
+  return agents.some(a => compareValue(a.val, condition_operator, condition_value))
+}
+
+function evaluateTaskRule(db: ReturnType<typeof getDatabase>, rule: AlertRule, _now: number): boolean {
+  const { condition_field, condition_operator, condition_value } = rule
+
+  if (condition_operator === 'count_above') {
+    const count = (db.prepare(`SELECT COUNT(*) as c FROM tasks WHERE ${safeColumn('tasks', condition_field)} = ?`).get(condition_value) as any)?.c || 0
+    return count > parseInt(condition_value)
+  }
+
+  if (condition_operator === 'count_below') {
+    const count = (db.prepare(`SELECT COUNT(*) as c FROM tasks`).get() as any)?.c || 0
+    return count < parseInt(condition_value)
+  }
+
+  const tasks = db.prepare(`SELECT ${safeColumn('tasks', condition_field)} as val FROM tasks`).all() as any[]
+  return tasks.some(t => compareValue(t.val, condition_operator, condition_value))
+}
+
+function evaluateSessionRule(db: ReturnType<typeof getDatabase>, rule: AlertRule, _now: number): boolean {
+  // Session data comes from the gateway, not the DB, so we check the agents table for session info
+  const { condition_operator, condition_value } = rule
+
+  if (condition_operator === 'count_above') {
+    const count = (db.prepare(`SELECT COUNT(*) as c FROM agents WHERE status = 'busy'`).get() as any)?.c || 0
+    return count > parseInt(condition_value)
+  }
+
+  return false
+}
+
+function evaluateActivityRule(db: ReturnType<typeof getDatabase>, rule: AlertRule, now: number): boolean {
+  const { condition_field, condition_operator, condition_value } = rule
+
+  if (condition_operator === 'count_above') {
+    // Count activities in the last hour
+    const hourAgo = now - 3600
+    const count = (db.prepare(`SELECT COUNT(*) as c FROM activities WHERE created_at > ? AND ${safeColumn('activities', condition_field)} = ?`).get(hourAgo, condition_value) as any)?.c || 0
+    return count > parseInt(condition_value)
+  }
+
+  return false
+}
+
+function compareValue(actual: any, operator: string, expected: string): boolean {
+  if (actual == null) return false
+  const strActual = String(actual)
+  switch (operator) {
+    case 'equals': return strActual === expected
+    case 'not_equals': return strActual !== expected
+    case 'greater_than': return Number(actual) > Number(expected)
+    case 'less_than': return Number(actual) < Number(expected)
+    case 'contains': return strActual.toLowerCase().includes(expected.toLowerCase())
+    default: return false
+  }
+}
+
+// Whitelist of columns per table to prevent SQL injection
+const SAFE_COLUMNS: Record<string, Set<string>> = {
+  agents: new Set(['status', 'role', 'name', 'last_seen', 'last_activity']),
+  tasks: new Set(['status', 'priority', 'assigned_to', 'title']),
+  activities: new Set(['type', 'actor', 'entity_type']),
+}
+
+function safeColumn(table: string, column: string): string {
+  if (SAFE_COLUMNS[table]?.has(column)) return column
+  return 'id' // fallback to safe column
+}

src/app/api/audit/route.ts

@@ -0,0 +1,66 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { getDatabase } from '@/lib/db'
+
+function safeParseJson(str: string): any {
+  try { return JSON.parse(str) } catch { return str }
+}
+
+/**
+ * GET /api/audit - Query audit log (admin only)
+ * Query params: action, actor, limit, offset, since, until
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const { searchParams } = new URL(request.url)
+  const action = searchParams.get('action')
+  const actor = searchParams.get('actor')
+  const limit = Math.min(parseInt(searchParams.get('limit') || '100'), 500)
+  const offset = parseInt(searchParams.get('offset') || '0')
+  const since = searchParams.get('since')
+  const until = searchParams.get('until')
+
+  const conditions: string[] = []
+  const params: any[] = []
+
+  if (action) {
+    conditions.push('action = ?')
+    params.push(action)
+  }
+  if (actor) {
+    conditions.push('actor = ?')
+    params.push(actor)
+  }
+  if (since) {
+    conditions.push('created_at >= ?')
+    params.push(parseInt(since))
+  }
+  if (until) {
+    conditions.push('created_at <= ?')
+    params.push(parseInt(until))
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+  const db = getDatabase()
+
+  const total = (db.prepare(`SELECT COUNT(*) as count FROM audit_log ${where}`).get(...params) as any).count
+
+  const rows = db.prepare(`
+    SELECT * FROM audit_log ${where}
+    ORDER BY created_at DESC
+    LIMIT ? OFFSET ?
+  `).all(...params, limit, offset)
+
+  return NextResponse.json({
+    events: rows.map((row: any) => ({
+      ...row,
+      detail: row.detail ? safeParseJson(row.detail) : null,
+    })),
+    total,
+    limit,
+    offset,
+  })
+}

src/app/api/auth/access-requests/route.ts

@@ -0,0 +1,147 @@
+import { randomBytes } from 'crypto'
+import { NextRequest, NextResponse } from 'next/server'
+import { createUser, getUserFromRequest } from '@/lib/auth'
+import { getDatabase, logAuditEvent } from '@/lib/db'
+
+function makeUsernameFromEmail(email: string): string {
+  const base = email.split('@')[0].replace(/[^a-z0-9._-]/gi, '').toLowerCase() || 'user'
+  return base.slice(0, 28)
+}
+
+function ensureUniqueUsername(base: string): string {
+  const db = getDatabase()
+  let candidate = base
+  let i = 0
+  while (db.prepare('SELECT 1 FROM users WHERE username = ?').get(candidate)) {
+    i += 1
+    candidate = `${base.slice(0, 24)}-${i}`
+  }
+  return candidate
+}
+
+export async function GET(request: NextRequest) {
+  const user = getUserFromRequest(request)
+  if (!user || user.role !== 'admin') {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 })
+  }
+
+  const db = getDatabase()
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS access_requests (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      provider TEXT NOT NULL DEFAULT 'google',
+      email TEXT NOT NULL,
+      provider_user_id TEXT,
+      display_name TEXT,
+      avatar_url TEXT,
+      status TEXT NOT NULL DEFAULT 'pending',
+      requested_at INTEGER NOT NULL DEFAULT (unixepoch()),
+      last_attempt_at INTEGER NOT NULL DEFAULT (unixepoch()),
+      attempt_count INTEGER NOT NULL DEFAULT 1,
+      reviewed_by TEXT,
+      reviewed_at INTEGER,
+      review_note TEXT,
+      approved_user_id INTEGER
+    )
+  `)
+
+  const status = String(request.nextUrl.searchParams.get('status') || 'all')
+  const rows = status === 'all'
+    ? db.prepare("SELECT * FROM access_requests ORDER BY status = 'pending' DESC, last_attempt_at DESC, id DESC").all()
+    : db.prepare('SELECT * FROM access_requests WHERE status = ? ORDER BY last_attempt_at DESC, id DESC').all(status)
+
+  return NextResponse.json({ requests: rows })
+}
+
+export async function POST(request: NextRequest) {
+  const admin = getUserFromRequest(request)
+  if (!admin || admin.role !== 'admin') {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 })
+  }
+
+  const db = getDatabase()
+  const body = await request.json().catch(() => ({}))
+  const requestId = Number(body?.request_id)
+  const action = String(body?.action || '')
+  const role = String(body?.role || 'viewer') as 'admin' | 'operator' | 'viewer'
+  const note = body?.note ? String(body.note) : null
+
+  if (!Number.isInteger(requestId) || requestId <= 0) {
+    return NextResponse.json({ error: 'request_id is required' }, { status: 400 })
+  }
+  if (!['approve', 'reject'].includes(action)) {
+    return NextResponse.json({ error: 'action must be approve or reject' }, { status: 400 })
+  }
+  if (!['admin', 'operator', 'viewer'].includes(role)) {
+    return NextResponse.json({ error: 'Invalid role' }, { status: 400 })
+  }
+
+  const reqRow = db.prepare('SELECT * FROM access_requests WHERE id = ?').get(requestId) as any
+  if (!reqRow) return NextResponse.json({ error: 'Request not found' }, { status: 404 })
+
+  if (action === 'reject') {
+    db.prepare(`
+      UPDATE access_requests
+      SET status = 'rejected', reviewed_by = ?, reviewed_at = (unixepoch()), review_note = ?
+      WHERE id = ?
+    `).run(admin.username, note, requestId)
+
+    logAuditEvent({
+      action: 'access_request_rejected',
+      actor: admin.username,
+      actor_id: admin.id,
+      detail: { request_id: requestId, email: reqRow.email, note },
+    })
+
+    return NextResponse.json({ ok: true })
+  }
+
+  const email = String(reqRow.email || '').toLowerCase()
+  const providerUserId = reqRow.provider_user_id ? String(reqRow.provider_user_id) : null
+  const displayName = String(reqRow.display_name || email.split('@')[0] || 'Google User')
+  const avatarUrl = reqRow.avatar_url ? String(reqRow.avatar_url) : null
+
+  const user = db.transaction(() => {
+    const existing = db.prepare('SELECT * FROM users WHERE lower(email) = ? OR (provider = ? AND provider_user_id = ?) ORDER BY id ASC LIMIT 1').get(email, 'google', providerUserId || '') as any
+
+    let userId: number
+    if (existing) {
+      db.prepare(`
+        UPDATE users
+        SET provider = 'google', provider_user_id = ?, email = ?, avatar_url = COALESCE(?, avatar_url), is_approved = 1, role = ?, approved_by = ?, approved_at = (unixepoch()), updated_at = (unixepoch())
+        WHERE id = ?
+      `).run(providerUserId, email, avatarUrl, role, admin.username, existing.id)
+      userId = Number(existing.id)
+    } else {
+      const username = ensureUniqueUsername(makeUsernameFromEmail(email))
+      const randomPwd = randomBytes(24).toString('hex')
+      const created = createUser(username, randomPwd, displayName, role, {
+        provider: 'google',
+        provider_user_id: providerUserId,
+        email,
+        avatar_url: avatarUrl,
+        is_approved: 1,
+        approved_by: admin.username,
+        approved_at: Math.floor(Date.now() / 1000),
+      })
+      userId = created.id
+    }
+
+    db.prepare(`
+      UPDATE access_requests
+      SET status = 'approved', reviewed_by = ?, reviewed_at = (unixepoch()), review_note = ?, approved_user_id = ?
+      WHERE id = ?
+    `).run(admin.username, note, userId, requestId)
+
+    return db.prepare('SELECT id, username, display_name, role, provider, email, avatar_url, is_approved FROM users WHERE id = ?').get(userId)
+  })() as any
+
+  logAuditEvent({
+    action: 'access_request_approved',
+    actor: admin.username,
+    actor_id: admin.id,
+    detail: { request_id: requestId, email, role, user_id: user?.id, note },
+  })
+
+  return NextResponse.json({ ok: true, user })
+}

src/app/api/auth/google/route.ts

@@ -0,0 +1,103 @@
+import { randomBytes } from 'crypto'
+import { NextResponse } from 'next/server'
+import { createSession } from '@/lib/auth'
+import { getDatabase, logAuditEvent } from '@/lib/db'
+import { verifyGoogleIdToken } from '@/lib/google-auth'
+import { getMcSessionCookieOptions } from '@/lib/session-cookie'
+
+function upsertAccessRequest(input: {
+  email: string
+  providerUserId: string
+  displayName: string
+  avatarUrl?: string
+}) {
+  const db = getDatabase()
+  db.prepare(`
+    INSERT INTO access_requests (provider, email, provider_user_id, display_name, avatar_url, status, attempt_count, requested_at, last_attempt_at)
+    VALUES ('google', ?, ?, ?, ?, 'pending', 1, (unixepoch()), (unixepoch()))
+    ON CONFLICT(email, provider) DO UPDATE SET
+      provider_user_id = excluded.provider_user_id,
+      display_name = excluded.display_name,
+      avatar_url = excluded.avatar_url,
+      status = 'pending',
+      attempt_count = access_requests.attempt_count + 1,
+      last_attempt_at = (unixepoch())
+  `).run(input.email.toLowerCase(), input.providerUserId, input.displayName, input.avatarUrl || null)
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json().catch(() => ({}))
+    const credential = String(body?.credential || '')
+    const profile = await verifyGoogleIdToken(credential)
+
+    const db = getDatabase()
+    const email = String(profile.email || '').toLowerCase().trim()
+    const sub = String(profile.sub || '').trim()
+    const displayName = String(profile.name || email.split('@')[0] || 'Google User').trim()
+    const avatar = profile.picture ? String(profile.picture) : null
+
+    const row = db.prepare(`
+      SELECT id, username, display_name, role, provider, email, avatar_url, is_approved, created_at, updated_at, last_login_at
+      FROM users
+      WHERE (provider = 'google' AND provider_user_id = ?) OR lower(email) = ?
+      ORDER BY id ASC
+      LIMIT 1
+    `).get(sub, email) as any
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    const userAgent = request.headers.get('user-agent') || undefined
+
+    if (!row || Number(row.is_approved ?? 1) !== 1) {
+      upsertAccessRequest({
+        email,
+        providerUserId: sub,
+        displayName,
+        avatarUrl: avatar || undefined,
+      })
+
+      logAuditEvent({
+        action: 'google_login_pending_approval',
+        actor: email,
+        detail: { email, sub },
+        ip_address: ipAddress,
+        user_agent: userAgent,
+      })
+
+      return NextResponse.json(
+        { error: 'Access request pending admin approval', code: 'PENDING_APPROVAL' },
+        { status: 403 }
+      )
+    }
+
+    db.prepare(`
+      UPDATE users
+      SET provider = 'google', provider_user_id = ?, email = ?, avatar_url = COALESCE(?, avatar_url), updated_at = (unixepoch())
+      WHERE id = ?
+    `).run(sub, email, avatar, row.id)
+
+    const { token, expiresAt } = createSession(row.id, ipAddress, userAgent)
+
+    logAuditEvent({ action: 'login_google', actor: row.username, actor_id: row.id, ip_address: ipAddress, user_agent: userAgent })
+
+    const response = NextResponse.json({
+      user: {
+        id: row.id,
+        username: row.username,
+        display_name: row.display_name,
+        role: row.role,
+        provider: 'google',
+        email,
+        avatar_url: avatar,
+      },
+    })
+
+    response.cookies.set('mc-session', token, {
+      ...getMcSessionCookieOptions({ maxAgeSeconds: expiresAt - Math.floor(Date.now() / 1000) }),
+    })
+
+    return response
+  } catch (error: any) {
+    return NextResponse.json({ error: error?.message || 'Google login failed' }, { status: 400 })
+  }
+}

src/app/api/auth/login/route.ts

@@ -0,0 +1,48 @@
+import { NextResponse } from 'next/server'
+import { authenticateUser, createSession } from '@/lib/auth'
+import { logAuditEvent } from '@/lib/db'
+import { getMcSessionCookieOptions } from '@/lib/session-cookie'
+
+export async function POST(request: Request) {
+  try {
+    const { username, password } = await request.json()
+
+    if (!username || !password) {
+      return NextResponse.json({ error: 'Username and password are required' }, { status: 400 })
+    }
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    const userAgent = request.headers.get('user-agent') || undefined
+
+    const user = authenticateUser(username, password)
+    if (!user) {
+      logAuditEvent({ action: 'login_failed', actor: username, ip_address: ipAddress, user_agent: userAgent })
+      return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 })
+    }
+
+    const { token, expiresAt } = createSession(user.id, ipAddress, userAgent)
+
+    logAuditEvent({ action: 'login', actor: user.username, actor_id: user.id, ip_address: ipAddress, user_agent: userAgent })
+
+    const response = NextResponse.json({
+      user: {
+        id: user.id,
+        username: user.username,
+        display_name: user.display_name,
+        role: user.role,
+        provider: user.provider || 'local',
+        email: user.email || null,
+        avatar_url: user.avatar_url || null,
+      },
+    })
+
+    response.cookies.set('mc-session', token, {
+      ...getMcSessionCookieOptions({ maxAgeSeconds: expiresAt - Math.floor(Date.now() / 1000) }),
+    })
+
+    return response
+  } catch (error) {
+    console.error('Login error:', error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}

src/app/api/auth/logout/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from 'next/server'
+import { destroySession, getUserFromRequest } from '@/lib/auth'
+import { logAuditEvent } from '@/lib/db'
+import { getMcSessionCookieOptions } from '@/lib/session-cookie'
+
+export async function POST(request: Request) {
+  const user = getUserFromRequest(request)
+  const cookieHeader = request.headers.get('cookie') || ''
+  const match = cookieHeader.match(/(?:^|;\s*)mc-session=([^;]*)/)
+  const token = match ? decodeURIComponent(match[1]) : null
+
+  if (token) {
+    destroySession(token)
+  }
+
+  if (user) {
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({ action: 'logout', actor: user.username, actor_id: user.id, ip_address: ipAddress })
+  }
+
+  const response = NextResponse.json({ ok: true })
+  response.cookies.set('mc-session', '', {
+    ...getMcSessionCookieOptions({ maxAgeSeconds: 0 }),
+  })
+
+  return response
+}

src/app/api/auth/me/route.ts

@@ -0,0 +1,108 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getUserFromRequest, updateUser } from '@/lib/auth'
+import { logAuditEvent } from '@/lib/db'
+import { verifyPassword } from '@/lib/password'
+
+export async function GET(request: Request) {
+  const user = getUserFromRequest(request)
+
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 })
+  }
+
+  return NextResponse.json({
+    user: {
+      id: user.id,
+      username: user.username,
+      display_name: user.display_name,
+      role: user.role,
+      provider: user.provider || 'local',
+      email: user.email || null,
+      avatar_url: user.avatar_url || null,
+    },
+  })
+}
+
+/**
+ * PATCH /api/auth/me - Self-service password change and display name update.
+ * Body: { current_password, new_password } and/or { display_name }
+ */
+export async function PATCH(request: NextRequest) {
+  const user = getUserFromRequest(request)
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 })
+  }
+
+  // API key users (id=0) cannot change passwords
+  if (user.id === 0) {
+    return NextResponse.json({ error: 'API key users cannot change passwords' }, { status: 403 })
+  }
+
+  try {
+    const { current_password, new_password, display_name } = await request.json()
+
+    const updates: { password?: string; display_name?: string } = {}
+
+    // Handle password change
+    if (new_password) {
+      if (!current_password) {
+        return NextResponse.json({ error: 'Current password is required' }, { status: 400 })
+      }
+
+      if (new_password.length < 8) {
+        return NextResponse.json({ error: 'New password must be at least 8 characters' }, { status: 400 })
+      }
+
+      // Verify current password by fetching stored hash
+      const { getDatabase } = await import('@/lib/db')
+      const db = getDatabase()
+      const row = db.prepare('SELECT password_hash FROM users WHERE id = ?').get(user.id) as any
+      if (!row || !verifyPassword(current_password, row.password_hash)) {
+        return NextResponse.json({ error: 'Current password is incorrect' }, { status: 403 })
+      }
+
+      updates.password = new_password
+    }
+
+    // Handle display name update
+    if (display_name !== undefined) {
+      if (!display_name.trim()) {
+        return NextResponse.json({ error: 'Display name cannot be empty' }, { status: 400 })
+      }
+      updates.display_name = display_name.trim()
+    }
+
+    if (Object.keys(updates).length === 0) {
+      return NextResponse.json({ error: 'No updates provided' }, { status: 400 })
+    }
+
+    const updated = updateUser(user.id, updates)
+    if (!updated) {
+      return NextResponse.json({ error: 'User not found' }, { status: 404 })
+    }
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    if (updates.password) {
+      logAuditEvent({ action: 'password_change', actor: user.username, actor_id: user.id, ip_address: ipAddress })
+    }
+    if (updates.display_name) {
+      logAuditEvent({ action: 'profile_update', actor: user.username, actor_id: user.id, detail: { display_name: updates.display_name }, ip_address: ipAddress })
+    }
+
+    return NextResponse.json({
+      success: true,
+      user: {
+        id: updated.id,
+        username: updated.username,
+        display_name: updated.display_name,
+        role: updated.role,
+        provider: updated.provider || 'local',
+        email: updated.email || null,
+        avatar_url: updated.avatar_url || null,
+      },
+    })
+  } catch (error) {
+    console.error('PATCH /api/auth/me error:', error)
+    return NextResponse.json({ error: 'Failed to update profile' }, { status: 500 })
+  }
+}

src/app/api/auth/users/route.ts

@@ -0,0 +1,159 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getUserFromRequest, getAllUsers, createUser, updateUser, deleteUser } from '@/lib/auth'
+import { logAuditEvent } from '@/lib/db'
+
+/**
+ * GET /api/auth/users - List all users (admin only)
+ */
+export async function GET(request: NextRequest) {
+  const user = getUserFromRequest(request)
+  if (!user || user.role !== 'admin') {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 })
+  }
+
+  const users = getAllUsers()
+  return NextResponse.json({ users })
+}
+
+/**
+ * POST /api/auth/users - Create a new user (admin only)
+ */
+export async function POST(request: NextRequest) {
+  const currentUser = getUserFromRequest(request)
+  if (!currentUser || currentUser.role !== 'admin') {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 })
+  }
+
+  try {
+    const { username, password, display_name, role = 'operator', provider = 'local', email = null } = await request.json()
+
+    if (!username || !password) {
+      return NextResponse.json({ error: 'Username and password are required' }, { status: 400 })
+    }
+
+    if (!['admin', 'operator', 'viewer'].includes(role)) {
+      return NextResponse.json({ error: 'Invalid role' }, { status: 400 })
+    }
+
+    const newUser = createUser(username, password, display_name || username, role, { provider, email })
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({
+      action: 'user_create', actor: currentUser.username, actor_id: currentUser.id,
+      target_type: 'user', target_id: newUser.id,
+      detail: { username, role, provider, email }, ip_address: ipAddress,
+    })
+
+    return NextResponse.json({
+      user: {
+        id: newUser.id,
+        username: newUser.username,
+        display_name: newUser.display_name,
+        role: newUser.role,
+        provider: newUser.provider || 'local',
+        email: newUser.email || null,
+        avatar_url: newUser.avatar_url || null,
+        is_approved: newUser.is_approved ?? 1,
+      }
+    }, { status: 201 })
+  } catch (error: any) {
+    if (error.message?.includes('UNIQUE constraint failed')) {
+      return NextResponse.json({ error: 'Username already exists' }, { status: 409 })
+    }
+    console.error('POST /api/auth/users error:', error)
+    return NextResponse.json({ error: 'Failed to create user' }, { status: 500 })
+  }
+}
+
+/**
+ * PUT /api/auth/users - Update a user (admin only)
+ */
+export async function PUT(request: NextRequest) {
+  const currentUser = getUserFromRequest(request)
+  if (!currentUser || currentUser.role !== 'admin') {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 })
+  }
+
+  try {
+    const { id, display_name, role, password, is_approved, email, avatar_url } = await request.json()
+
+    if (!id) {
+      return NextResponse.json({ error: 'User ID is required' }, { status: 400 })
+    }
+
+    if (role && !['admin', 'operator', 'viewer'].includes(role)) {
+      return NextResponse.json({ error: 'Invalid role' }, { status: 400 })
+    }
+
+    // Prevent demoting yourself
+    if (id === currentUser.id && role && role !== currentUser.role) {
+      return NextResponse.json({ error: 'Cannot change your own role' }, { status: 400 })
+    }
+
+    const updated = updateUser(id, { display_name, role, password: password || undefined, is_approved, email, avatar_url })
+    if (!updated) {
+      return NextResponse.json({ error: 'User not found' }, { status: 404 })
+    }
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({
+      action: 'user_update', actor: currentUser.username, actor_id: currentUser.id,
+      target_type: 'user', target_id: id,
+      detail: { display_name, role, password_changed: !!password, is_approved }, ip_address: ipAddress,
+    })
+
+    return NextResponse.json({
+      user: {
+        id: updated.id,
+        username: updated.username,
+        display_name: updated.display_name,
+        role: updated.role,
+        provider: updated.provider || 'local',
+        email: updated.email || null,
+        avatar_url: updated.avatar_url || null,
+        is_approved: updated.is_approved ?? 1,
+      }
+    })
+  } catch (error) {
+    console.error('PUT /api/auth/users error:', error)
+    return NextResponse.json({ error: 'Failed to update user' }, { status: 500 })
+  }
+}
+
+/**
+ * DELETE /api/auth/users - Delete a user (admin only)
+ */
+export async function DELETE(request: NextRequest) {
+  const currentUser = getUserFromRequest(request)
+  if (!currentUser || currentUser.role !== 'admin') {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 })
+  }
+
+  const { searchParams } = new URL(request.url)
+  const id = searchParams.get('id')
+
+  if (!id) {
+    return NextResponse.json({ error: 'User ID is required' }, { status: 400 })
+  }
+
+  const userId = parseInt(id)
+
+  // Prevent deleting yourself
+  if (userId === currentUser.id) {
+    return NextResponse.json({ error: 'Cannot delete your own account' }, { status: 400 })
+  }
+
+  const deleted = deleteUser(userId)
+  if (!deleted) {
+    return NextResponse.json({ error: 'User not found' }, { status: 404 })
+  }
+
+  const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+  logAuditEvent({
+    action: 'user_delete', actor: currentUser.username, actor_id: currentUser.id,
+    target_type: 'user', target_id: userId,
+    ip_address: ipAddress,
+  })
+
+  return NextResponse.json({ success: true })
+}

src/app/api/backup/route.ts

@@ -0,0 +1,129 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { getDatabase, logAuditEvent } from '@/lib/db'
+import { config, ensureDirExists } from '@/lib/config'
+import { join, dirname } from 'path'
+import { readdirSync, statSync, unlinkSync } from 'fs'
+
+const BACKUP_DIR = join(dirname(config.dbPath), 'backups')
+const MAX_BACKUPS = 10
+
+/**
+ * GET /api/backup - List existing backups (admin only)
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  ensureDirExists(BACKUP_DIR)
+
+  try {
+    const files = readdirSync(BACKUP_DIR)
+      .filter(f => f.endsWith('.db'))
+      .map(f => {
+        const stat = statSync(join(BACKUP_DIR, f))
+        return {
+          name: f,
+          size: stat.size,
+          created_at: Math.floor(stat.mtimeMs / 1000),
+        }
+      })
+      .sort((a, b) => b.created_at - a.created_at)
+
+    return NextResponse.json({ backups: files, dir: BACKUP_DIR })
+  } catch {
+    return NextResponse.json({ backups: [], dir: BACKUP_DIR })
+  }
+}
+
+/**
+ * POST /api/backup - Create a new backup (admin only)
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  ensureDirExists(BACKUP_DIR)
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19)
+  const backupPath = join(BACKUP_DIR, `mc-backup-${timestamp}.db`)
+
+  try {
+    const db = getDatabase()
+    await db.backup(backupPath)
+
+    const stat = statSync(backupPath)
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({
+      action: 'backup_create',
+      actor: auth.user.username,
+      actor_id: auth.user.id,
+      detail: { path: backupPath, size: stat.size },
+      ip_address: ipAddress,
+    })
+
+    // Prune old backups beyond MAX_BACKUPS
+    pruneOldBackups()
+
+    return NextResponse.json({
+      success: true,
+      backup: {
+        name: `mc-backup-${timestamp}.db`,
+        size: stat.size,
+        created_at: Math.floor(stat.mtimeMs / 1000),
+      },
+    })
+  } catch (error: any) {
+    console.error('Backup failed:', error)
+    return NextResponse.json({ error: `Backup failed: ${error.message}` }, { status: 500 })
+  }
+}
+
+/**
+ * DELETE /api/backup?name=<filename> - Delete a specific backup (admin only)
+ */
+export async function DELETE(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const { searchParams } = new URL(request.url)
+  const name = searchParams.get('name')
+
+  if (!name || !name.endsWith('.db') || name.includes('/') || name.includes('..')) {
+    return NextResponse.json({ error: 'Invalid backup name' }, { status: 400 })
+  }
+
+  try {
+    const fullPath = join(BACKUP_DIR, name)
+    unlinkSync(fullPath)
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({
+      action: 'backup_delete',
+      actor: auth.user.username,
+      actor_id: auth.user.id,
+      detail: { name },
+      ip_address: ipAddress,
+    })
+
+    return NextResponse.json({ success: true })
+  } catch {
+    return NextResponse.json({ error: 'Backup not found' }, { status: 404 })
+  }
+}
+
+function pruneOldBackups() {
+  try {
+    const files = readdirSync(BACKUP_DIR)
+      .filter(f => f.startsWith('mc-backup-') && f.endsWith('.db'))
+      .map(f => ({ name: f, mtime: statSync(join(BACKUP_DIR, f)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime)
+
+    for (const file of files.slice(MAX_BACKUPS)) {
+      unlinkSync(join(BACKUP_DIR, file.name))
+    }
+  } catch {
+    // Best-effort pruning
+  }
+}

src/app/api/chat/conversations/route.ts

@@ -0,0 +1,79 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getDatabase } from '@/lib/db'
+
+/**
+ * GET /api/chat/conversations - List conversations derived from messages
+ * Query params: agent (filter by participant), limit, offset
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const db = getDatabase()
+    const { searchParams } = new URL(request.url)
+
+    const agent = searchParams.get('agent')
+    const limit = parseInt(searchParams.get('limit') || '50')
+    const offset = parseInt(searchParams.get('offset') || '0')
+
+    let query: string
+    const params: any[] = []
+
+    if (agent) {
+      // Get conversations where this agent is a participant
+      query = `
+        SELECT
+          m.conversation_id,
+          MAX(m.created_at) as last_message_at,
+          COUNT(*) as message_count,
+          COUNT(DISTINCT m.from_agent) + COUNT(DISTINCT CASE WHEN m.to_agent IS NOT NULL THEN m.to_agent END) as participant_count,
+          SUM(CASE WHEN m.to_agent = ? AND m.read_at IS NULL THEN 1 ELSE 0 END) as unread_count
+        FROM messages m
+        WHERE m.from_agent = ? OR m.to_agent = ? OR m.to_agent IS NULL
+        GROUP BY m.conversation_id
+        ORDER BY last_message_at DESC
+        LIMIT ? OFFSET ?
+      `
+      params.push(agent, agent, agent, limit, offset)
+    } else {
+      query = `
+        SELECT
+          m.conversation_id,
+          MAX(m.created_at) as last_message_at,
+          COUNT(*) as message_count,
+          COUNT(DISTINCT m.from_agent) + COUNT(DISTINCT CASE WHEN m.to_agent IS NOT NULL THEN m.to_agent END) as participant_count,
+          0 as unread_count
+        FROM messages m
+        GROUP BY m.conversation_id
+        ORDER BY last_message_at DESC
+        LIMIT ? OFFSET ?
+      `
+      params.push(limit, offset)
+    }
+
+    const conversations = db.prepare(query).all(...params) as any[]
+
+    // Fetch the last message for each conversation
+    const withLastMessage = conversations.map((conv) => {
+      const lastMsg = db.prepare(`
+        SELECT * FROM messages
+        WHERE conversation_id = ?
+        ORDER BY created_at DESC
+        LIMIT 1
+      `).get(conv.conversation_id) as any
+
+      return {
+        ...conv,
+        last_message: lastMsg
+          ? {
+              ...lastMsg,
+              metadata: lastMsg.metadata ? JSON.parse(lastMsg.metadata) : null
+            }
+          : null
+      }
+    })
+
+    return NextResponse.json({ conversations: withLastMessage, total: withLastMessage.length })
+  } catch (error) {
+    console.error('GET /api/chat/conversations error:', error)
+    return NextResponse.json({ error: 'Failed to fetch conversations' }, { status: 500 })
+  }
+}

src/app/api/chat/messages/[id]/route.ts

@@ -0,0 +1,72 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getDatabase, Message } from '@/lib/db'
+import { requireRole } from '@/lib/auth'
+
+/**
+ * GET /api/chat/messages/[id] - Get a single message
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const db = getDatabase()
+    const { id } = await params
+
+    const message = db.prepare('SELECT * FROM messages WHERE id = ?').get(parseInt(id)) as Message | undefined
+
+    if (!message) {
+      return NextResponse.json({ error: 'Message not found' }, { status: 404 })
+    }
+
+    return NextResponse.json({
+      message: {
+        ...message,
+        metadata: message.metadata ? JSON.parse(message.metadata) : null
+      }
+    })
+  } catch (error) {
+    console.error('GET /api/chat/messages/[id] error:', error)
+    return NextResponse.json({ error: 'Failed to fetch message' }, { status: 500 })
+  }
+}
+
+/**
+ * PATCH /api/chat/messages/[id] - Mark message as read
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const db = getDatabase()
+    const { id } = await params
+    const body = await request.json()
+
+    const message = db.prepare('SELECT * FROM messages WHERE id = ?').get(parseInt(id)) as Message | undefined
+
+    if (!message) {
+      return NextResponse.json({ error: 'Message not found' }, { status: 404 })
+    }
+
+    if (body.read) {
+      const now = Math.floor(Date.now() / 1000)
+      db.prepare('UPDATE messages SET read_at = ? WHERE id = ?').run(now, parseInt(id))
+    }
+
+    const updated = db.prepare('SELECT * FROM messages WHERE id = ?').get(parseInt(id)) as Message
+
+    return NextResponse.json({
+      message: {
+        ...updated,
+        metadata: updated.metadata ? JSON.parse(updated.metadata) : null
+      }
+    })
+  } catch (error) {
+    console.error('PATCH /api/chat/messages/[id] error:', error)
+    return NextResponse.json({ error: 'Failed to update message' }, { status: 500 })
+  }
+}

src/app/api/chat/messages/route.ts

@@ -0,0 +1,459 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { getDatabase, db_helpers, Message } from '@/lib/db'
+import { runOpenClaw } from '@/lib/command'
+import { getAllGatewaySessions } from '@/lib/sessions'
+import { eventBus } from '@/lib/event-bus'
+import { requireRole } from '@/lib/auth'
+
+type ForwardInfo = {
+  attempted: boolean
+  delivered: boolean
+  reason?: string
+  session?: string
+  runId?: string
+}
+
+const COORDINATOR_AGENT =
+  String(process.env.MC_COORDINATOR_AGENT || process.env.NEXT_PUBLIC_COORDINATOR_AGENT || 'coordinator').trim() ||
+  'coordinator'
+
+function parseGatewayJson(raw: string): any | null {
+  const trimmed = String(raw || '').trim()
+  if (!trimmed) return null
+  const start = trimmed.indexOf('{')
+  const end = trimmed.lastIndexOf('}')
+  if (start < 0 || end < start) return null
+  try {
+    return JSON.parse(trimmed.slice(start, end + 1))
+  } catch {
+    return null
+  }
+}
+
+function createChatReply(
+  db: ReturnType<typeof getDatabase>,
+  conversationId: string,
+  fromAgent: string,
+  toAgent: string,
+  content: string,
+  messageType: 'text' | 'status' = 'status',
+  metadata: Record<string, any> | null = null
+) {
+  const replyInsert = db
+    .prepare(`
+      INSERT INTO messages (conversation_id, from_agent, to_agent, content, message_type, metadata)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `)
+    .run(
+      conversationId,
+      fromAgent,
+      toAgent,
+      content,
+      messageType,
+      metadata ? JSON.stringify(metadata) : null
+    )
+
+  const row = db
+    .prepare('SELECT * FROM messages WHERE id = ?')
+    .get(replyInsert.lastInsertRowid) as Message
+
+  eventBus.broadcast('chat.message', {
+    ...row,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
+  })
+}
+
+function extractReplyText(waitPayload: any): string | null {
+  if (!waitPayload || typeof waitPayload !== 'object') return null
+
+  const directCandidates = [
+    waitPayload.text,
+    waitPayload.message,
+    waitPayload.response,
+    waitPayload.output,
+    waitPayload.result,
+  ]
+  for (const value of directCandidates) {
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+
+  if (typeof waitPayload.output === 'object' && waitPayload.output) {
+    const nested = [
+      waitPayload.output.text,
+      waitPayload.output.message,
+      waitPayload.output.content,
+    ]
+    for (const value of nested) {
+      if (typeof value === 'string' && value.trim()) return value.trim()
+    }
+  }
+
+  return null
+}
+
+/**
+ * GET /api/chat/messages - List messages with filters
+ * Query params: conversation_id, from_agent, to_agent, limit, offset, since
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const db = getDatabase()
+    const { searchParams } = new URL(request.url)
+
+    const conversation_id = searchParams.get('conversation_id')
+    const from_agent = searchParams.get('from_agent')
+    const to_agent = searchParams.get('to_agent')
+    const limit = parseInt(searchParams.get('limit') || '50')
+    const offset = parseInt(searchParams.get('offset') || '0')
+    const since = searchParams.get('since')
+
+    let query = 'SELECT * FROM messages WHERE 1=1'
+    const params: any[] = []
+
+    if (conversation_id) {
+      query += ' AND conversation_id = ?'
+      params.push(conversation_id)
+    }
+
+    if (from_agent) {
+      query += ' AND from_agent = ?'
+      params.push(from_agent)
+    }
+
+    if (to_agent) {
+      query += ' AND to_agent = ?'
+      params.push(to_agent)
+    }
+
+    if (since) {
+      query += ' AND created_at > ?'
+      params.push(parseInt(since))
+    }
+
+    query += ' ORDER BY created_at ASC LIMIT ? OFFSET ?'
+    params.push(limit, offset)
+
+    const messages = db.prepare(query).all(...params) as Message[]
+
+    const parsed = messages.map((msg) => ({
+      ...msg,
+      metadata: msg.metadata ? JSON.parse(msg.metadata) : null
+    }))
+
+    return NextResponse.json({ messages: parsed, total: parsed.length })
+  } catch (error) {
+    console.error('GET /api/chat/messages error:', error)
+    return NextResponse.json({ error: 'Failed to fetch messages' }, { status: 500 })
+  }
+}
+
+/**
+ * POST /api/chat/messages - Send a new message
+ * Body: { from, to, content, message_type, conversation_id, metadata }
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'operator')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const db = getDatabase()
+    const body = await request.json()
+
+    const from = (body.from || '').trim()
+    const to = body.to ? (body.to as string).trim() : null
+    const content = (body.content || '').trim()
+    const message_type = body.message_type || 'text'
+    const conversation_id = body.conversation_id || `conv_${Date.now()}`
+    const metadata = body.metadata || null
+
+    if (!from || !content) {
+      return NextResponse.json(
+        { error: '"from" and "content" are required' },
+        { status: 400 }
+      )
+    }
+
+    const stmt = db.prepare(`
+      INSERT INTO messages (conversation_id, from_agent, to_agent, content, message_type, metadata)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `)
+
+    const result = stmt.run(
+      conversation_id,
+      from,
+      to,
+      content,
+      message_type,
+      metadata ? JSON.stringify(metadata) : null
+    )
+
+    const messageId = result.lastInsertRowid as number
+
+    let forwardInfo: ForwardInfo | null = null
+
+    // Log activity
+    db_helpers.logActivity(
+      'chat_message',
+      'message',
+      messageId,
+      from,
+      `Sent ${message_type} message${to ? ` to ${to}` : ' (broadcast)'}`,
+      { conversation_id, to, message_type }
+    )
+
+    // Create notification for recipient if specified
+    if (to) {
+      db_helpers.createNotification(
+        to,
+        'chat_message',
+        `Message from ${from}`,
+        content.substring(0, 200) + (content.length > 200 ? '...' : ''),
+        'message',
+        messageId
+      )
+
+      // Optionally forward to agent via gateway
+      if (body.forward) {
+        forwardInfo = { attempted: true, delivered: false }
+
+        const agent = db
+          .prepare('SELECT * FROM agents WHERE lower(name) = lower(?)')
+          .get(to) as any
+
+        let sessionKey: string | null = agent?.session_key || null
+
+        // Fallback: derive session from on-disk gateway session stores
+        if (!sessionKey) {
+          const sessions = getAllGatewaySessions()
+          const match = sessions.find(
+            (s) => s.agent.toLowerCase() === String(to).toLowerCase()
+          )
+          sessionKey = match?.key || match?.sessionId || null
+        }
+
+        // Prefer configured openclawId when present, fallback to normalized name
+        let openclawAgentId: string | null = null
+        if (agent?.config) {
+          try {
+            const cfg = JSON.parse(agent.config)
+            if (cfg?.openclawId && typeof cfg.openclawId === 'string') {
+              openclawAgentId = cfg.openclawId
+            }
+          } catch {
+            // ignore parse issues
+          }
+        }
+        if (!openclawAgentId && typeof to === 'string') {
+          openclawAgentId = to.toLowerCase().replace(/\s+/g, '-')
+        }
+
+        if (!sessionKey && !openclawAgentId) {
+          forwardInfo.reason = 'no_active_session'
+
+          // For coordinator messages, emit an immediate visible status reply
+          if (typeof conversation_id === 'string' && conversation_id.startsWith('coord:')) {
+            try {
+                createChatReply(
+                  db,
+                  conversation_id,
+                  COORDINATOR_AGENT,
+                  from,
+                  'I received your message, but my live coordinator session is offline right now. Start/restore the coordinator session and retry.',
+                  'status',
+                  { status: 'offline', reason: 'no_active_session' }
+                )
+            } catch (e) {
+              console.error('Failed to create offline status reply:', e)
+            }
+          }
+        } else {
+          try {
+            const invokeParams: any = {
+              message: `Message from ${from}: ${content}`,
+              idempotencyKey: `mc-${messageId}-${Date.now()}`,
+              deliver: false,
+            }
+            if (sessionKey) invokeParams.sessionKey = sessionKey
+            else invokeParams.agentId = openclawAgentId
+
+            const invokeResult = await runOpenClaw(
+              [
+                'gateway',
+                'call',
+                'agent',
+                '--timeout',
+                '10000',
+                '--params',
+                JSON.stringify(invokeParams),
+                '--json',
+              ],
+              { timeoutMs: 12000 }
+            )
+            const acceptedPayload = parseGatewayJson(invokeResult.stdout)
+            forwardInfo.delivered = true
+            forwardInfo.session = sessionKey || openclawAgentId || undefined
+            if (typeof acceptedPayload?.runId === 'string' && acceptedPayload.runId) {
+              forwardInfo.runId = acceptedPayload.runId
+            }
+          } catch (err) {
+            // OpenClaw may return accepted JSON on stdout but still emit a late stderr warning.
+            // Treat accepted runs as successful delivery.
+            const maybeStdout = String((err as any)?.stdout || '')
+            const acceptedPayload = parseGatewayJson(maybeStdout)
+            if (maybeStdout.includes('"status": "accepted"') || maybeStdout.includes('"status":"accepted"')) {
+              forwardInfo.delivered = true
+              forwardInfo.session = sessionKey || openclawAgentId || undefined
+              if (typeof acceptedPayload?.runId === 'string' && acceptedPayload.runId) {
+                forwardInfo.runId = acceptedPayload.runId
+              }
+            } else {
+              forwardInfo.reason = 'gateway_send_failed'
+              console.error('Failed to forward message via gateway:', err)
+
+              // For coordinator messages, emit visible status when send fails
+              if (typeof conversation_id === 'string' && conversation_id.startsWith('coord:')) {
+                try {
+                  createChatReply(
+                    db,
+                    conversation_id,
+                    COORDINATOR_AGENT,
+                    from,
+                    'I received your message, but delivery to the live coordinator runtime failed. Please restart the coordinator/gateway session and retry.',
+                    'status',
+                    { status: 'delivery_failed', reason: 'gateway_send_failed' }
+                  )
+                } catch (e) {
+                  console.error('Failed to create gateway failure status reply:', e)
+                }
+              }
+            }
+          }
+
+          // Coordinator mode should always show visible coordinator feedback in thread.
+          if (
+            typeof conversation_id === 'string' &&
+            conversation_id.startsWith('coord:') &&
+            forwardInfo.delivered
+          ) {
+            try {
+              createChatReply(
+                db,
+                conversation_id,
+                COORDINATOR_AGENT,
+                from,
+                'Received. I am coordinating downstream agents now.',
+                'status',
+                { status: 'accepted', runId: forwardInfo.runId || null }
+              )
+            } catch (e) {
+              console.error('Failed to create accepted status reply:', e)
+            }
+
+            // Best effort: wait briefly and surface completion/error feedback.
+            if (forwardInfo.runId) {
+              try {
+                const waitResult = await runOpenClaw(
+                  [
+                    'gateway',
+                    'call',
+                    'agent.wait',
+                    '--timeout',
+                    '8000',
+                    '--params',
+                    JSON.stringify({ runId: forwardInfo.runId, timeoutMs: 6000 }),
+                    '--json',
+                  ],
+                  { timeoutMs: 9000 }
+                )
+
+                const waitPayload = parseGatewayJson(waitResult.stdout)
+                const waitStatus = String(waitPayload?.status || '').toLowerCase()
+
+                if (waitStatus === 'error') {
+                  const reason =
+                    typeof waitPayload?.error === 'string'
+                      ? waitPayload.error
+                      : 'Unknown runtime error'
+                  createChatReply(
+                    db,
+                    conversation_id,
+                    COORDINATOR_AGENT,
+                    from,
+                    `I received your message, but execution failed: ${reason}`,
+                    'status',
+                    { status: 'error', runId: forwardInfo.runId }
+                  )
+                } else if (waitStatus === 'timeout') {
+                  createChatReply(
+                    db,
+                    conversation_id,
+                    COORDINATOR_AGENT,
+                    from,
+                    'I received your message and I am still processing it. I will post results as soon as execution completes.',
+                    'status',
+                    { status: 'processing', runId: forwardInfo.runId }
+                  )
+                } else {
+                  const replyText = extractReplyText(waitPayload)
+                  if (replyText) {
+                    createChatReply(
+                      db,
+                      conversation_id,
+                      COORDINATOR_AGENT,
+                      from,
+                      replyText,
+                      'text',
+                      { status: waitStatus || 'completed', runId: forwardInfo.runId }
+                    )
+                  } else {
+                    createChatReply(
+                      db,
+                      conversation_id,
+                      COORDINATOR_AGENT,
+                      from,
+                      'Execution accepted and completed. No textual response payload was returned by the runtime.',
+                      'status',
+                      { status: waitStatus || 'completed', runId: forwardInfo.runId }
+                    )
+                  }
+                }
+              } catch (waitErr) {
+                const maybeWaitStdout = String((waitErr as any)?.stdout || '')
+                const maybeWaitStderr = String((waitErr as any)?.stderr || '')
+                const waitPayload = parseGatewayJson(maybeWaitStdout)
+                const reason =
+                  typeof waitPayload?.error === 'string'
+                    ? waitPayload.error
+                    : (maybeWaitStderr || maybeWaitStdout || 'Unable to read completion status from coordinator runtime.').trim()
+
+                createChatReply(
+                  db,
+                  conversation_id,
+                  COORDINATOR_AGENT,
+                  from,
+                  `I received your message, but I could not retrieve completion output yet: ${reason}`,
+                  'status',
+                  { status: 'unknown', runId: forwardInfo.runId }
+                )
+              }
+            }
+          }
+        }
+      }
+    }
+
+    const created = db.prepare('SELECT * FROM messages WHERE id = ?').get(messageId) as Message
+    const parsedMessage = {
+      ...created,
+      metadata: created.metadata ? JSON.parse(created.metadata) : null
+    }
+
+    // Broadcast to SSE clients
+    eventBus.broadcast('chat.message', parsedMessage)
+
+    return NextResponse.json({ message: parsedMessage, forward: forwardInfo }, { status: 201 })
+  } catch (error) {
+    console.error('POST /api/chat/messages error:', error)
+    return NextResponse.json({ error: 'Failed to send message' }, { status: 500 })
+  }
+}

src/app/api/cleanup/route.ts

@@ -0,0 +1,162 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { getDatabase, logAuditEvent } from '@/lib/db'
+import { config } from '@/lib/config'
+
+interface CleanupResult {
+  table: string
+  deleted: number
+  cutoff_date: string
+  retention_days: number
+}
+
+/**
+ * GET /api/cleanup - Show retention policy and what would be cleaned
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const db = getDatabase()
+  const now = Math.floor(Date.now() / 1000)
+  const ret = config.retention
+
+  const preview = []
+
+  for (const { table, column, days, label } of getRetentionTargets()) {
+    if (days <= 0) {
+      preview.push({ table: label, retention_days: 0, stale_count: 0, note: 'Retention disabled (keep forever)' })
+      continue
+    }
+    const cutoff = now - days * 86400
+    try {
+      const row = db.prepare(`SELECT COUNT(*) as c FROM ${table} WHERE ${column} < ?`).get(cutoff) as any
+      preview.push({
+        table: label,
+        retention_days: days,
+        cutoff_date: new Date(cutoff * 1000).toISOString().split('T')[0],
+        stale_count: row.c,
+      })
+    } catch {
+      preview.push({ table: label, retention_days: days, stale_count: 0, note: 'Table not found' })
+    }
+  }
+
+  // Token usage file stats
+  try {
+    const { readFile } = require('fs/promises')
+    const data = JSON.parse(await readFile(config.tokensPath, 'utf-8'))
+    const cutoffMs = Date.now() - ret.tokenUsage * 86400000
+    const stale = data.filter((r: any) => r.timestamp < cutoffMs).length
+    preview.push({
+      table: 'Token Usage (file)',
+      retention_days: ret.tokenUsage,
+      cutoff_date: new Date(cutoffMs).toISOString().split('T')[0],
+      stale_count: stale,
+    })
+  } catch {
+    preview.push({ table: 'Token Usage (file)', retention_days: ret.tokenUsage, stale_count: 0, note: 'No token data file' })
+  }
+
+  return NextResponse.json({ retention: config.retention, preview })
+}
+
+/**
+ * POST /api/cleanup - Run cleanup (admin only)
+ * Body: { dry_run?: boolean }
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const body = await request.json().catch(() => ({}))
+  const dryRun = body.dry_run === true
+
+  const db = getDatabase()
+  const now = Math.floor(Date.now() / 1000)
+  const results: CleanupResult[] = []
+  let totalDeleted = 0
+
+  for (const { table, column, days, label } of getRetentionTargets()) {
+    if (days <= 0) continue
+    const cutoff = now - days * 86400
+
+    try {
+      if (dryRun) {
+        const row = db.prepare(`SELECT COUNT(*) as c FROM ${table} WHERE ${column} < ?`).get(cutoff) as any
+        results.push({
+          table: label,
+          deleted: row.c,
+          cutoff_date: new Date(cutoff * 1000).toISOString().split('T')[0],
+          retention_days: days,
+        })
+        totalDeleted += row.c
+      } else {
+        const res = db.prepare(`DELETE FROM ${table} WHERE ${column} < ?`).run(cutoff)
+        results.push({
+          table: label,
+          deleted: res.changes,
+          cutoff_date: new Date(cutoff * 1000).toISOString().split('T')[0],
+          retention_days: days,
+        })
+        totalDeleted += res.changes
+      }
+    } catch {
+      results.push({ table: label, deleted: 0, cutoff_date: '', retention_days: days })
+    }
+  }
+
+  // Clean token usage file
+  const ret = config.retention
+  if (ret.tokenUsage > 0) {
+    try {
+      const { readFile, writeFile } = require('fs/promises')
+      const raw = await readFile(config.tokensPath, 'utf-8')
+      const data = JSON.parse(raw)
+      const cutoffMs = Date.now() - ret.tokenUsage * 86400000
+      const kept = data.filter((r: any) => r.timestamp >= cutoffMs)
+      const removed = data.length - kept.length
+
+      if (!dryRun && removed > 0) {
+        await writeFile(config.tokensPath, JSON.stringify(kept, null, 2))
+      }
+
+      results.push({
+        table: 'Token Usage (file)',
+        deleted: removed,
+        cutoff_date: new Date(cutoffMs).toISOString().split('T')[0],
+        retention_days: ret.tokenUsage,
+      })
+      totalDeleted += removed
+    } catch {
+      // No token file or parse error
+    }
+  }
+
+  if (!dryRun && totalDeleted > 0) {
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({
+      action: 'data_cleanup',
+      actor: auth.user.username,
+      actor_id: auth.user.id,
+      detail: { total_deleted: totalDeleted, results },
+      ip_address: ipAddress,
+    })
+  }
+
+  return NextResponse.json({
+    dry_run: dryRun,
+    total_deleted: totalDeleted,
+    results,
+  })
+}
+
+function getRetentionTargets() {
+  const ret = config.retention
+  return [
+    { table: 'activities', column: 'created_at', days: ret.activities, label: 'Activities' },
+    { table: 'audit_log', column: 'created_at', days: ret.auditLog, label: 'Audit Log' },
+    { table: 'notifications', column: 'created_at', days: ret.notifications, label: 'Notifications' },
+    { table: 'pipeline_runs', column: 'created_at', days: ret.pipelineRuns, label: 'Pipeline Runs' },
+  ]
+}

src/app/api/cron/route.ts

@@ -0,0 +1,341 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { config } from '@/lib/config'
+import fs from 'node:fs'
+import path from 'node:path'
+
+interface CronJob {
+  name: string
+  schedule: string
+  command: string
+  enabled: boolean
+  lastRun?: number
+  nextRun?: number
+  lastStatus?: 'success' | 'error' | 'running'
+  lastError?: string
+  // Extended fields from OpenClaw format
+  id?: string
+  agentId?: string
+  timezone?: string
+  model?: string
+  delivery?: string
+}
+
+/**
+ * OpenClaw cron jobs live in ~/.openclaw/cron/jobs.json
+ * Format: { version: 1, jobs: [ { id, agentId, name, enabled, schedule: { kind, expr, tz }, payload, delivery, state } ] }
+ */
+interface OpenClawCronJob {
+  id: string
+  agentId: string
+  name: string
+  enabled: boolean
+  createdAtMs?: number
+  updatedAtMs?: number
+  schedule: {
+    kind: string
+    expr: string
+    tz?: string
+  }
+  sessionTarget?: string
+  wakeMode?: string
+  payload: {
+    kind: string
+    message?: string
+    model?: string
+    thinking?: string
+    timeoutSeconds?: number
+  }
+  delivery?: {
+    mode: string
+    channel?: string
+    to?: string
+  }
+  state?: {
+    nextRunAtMs?: number
+    lastRunAtMs?: number
+    lastStatus?: string
+    lastDurationMs?: number
+    lastError?: string
+  }
+}
+
+interface OpenClawCronFile {
+  version: number
+  jobs: OpenClawCronJob[]
+}
+
+function getCronFilePath(): string {
+  const openclawHome = config.openclawHome
+  if (!openclawHome) return ''
+  return path.join(openclawHome, 'cron', 'jobs.json')
+}
+
+function loadCronFile(): OpenClawCronFile | null {
+  const filePath = getCronFilePath()
+  if (!filePath) return null
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8')
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+function saveCronFile(data: OpenClawCronFile): boolean {
+  const filePath = getCronFilePath()
+  if (!filePath) return false
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2))
+    return true
+  } catch (err) {
+    console.error('Failed to write cron file:', err)
+    return false
+  }
+}
+
+function mapLastStatus(status?: string): 'success' | 'error' | 'running' | undefined {
+  if (!status) return undefined
+  const s = status.toLowerCase()
+  if (s === 'success' || s === 'completed' || s === 'updated') return 'success'
+  if (s === 'error' || s === 'failed') return 'error'
+  if (s === 'running' || s === 'pending') return 'running'
+  return 'success' // default for unknown non-error statuses
+}
+
+function mapOpenClawJob(job: OpenClawCronJob): CronJob {
+  // Build a human-readable command description from the payload
+  const payloadSummary = job.payload.message
+    ? job.payload.message.slice(0, 200) + (job.payload.message.length > 200 ? '...' : '')
+    : `${job.payload.kind} (${job.agentId})`
+
+  const scheduleStr = job.schedule.tz
+    ? `${job.schedule.expr} (${job.schedule.tz})`
+    : job.schedule.expr
+
+  return {
+    id: job.id,
+    name: job.name,
+    schedule: scheduleStr,
+    command: payloadSummary,
+    enabled: job.enabled,
+    lastRun: job.state?.lastRunAtMs,
+    nextRun: job.state?.nextRunAtMs,
+    lastStatus: mapLastStatus(job.state?.lastStatus),
+    lastError: job.state?.lastError,
+    agentId: job.agentId,
+    timezone: job.schedule.tz,
+    model: job.payload.model,
+    delivery: job.delivery?.mode === 'none' ? undefined : job.delivery?.channel,
+  }
+}
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url)
+    const action = searchParams.get('action')
+
+    if (action === 'list') {
+      const cronFile = loadCronFile()
+      if (!cronFile || !cronFile.jobs) {
+        return NextResponse.json({ jobs: [] })
+      }
+
+      const jobs = cronFile.jobs.map(mapOpenClawJob)
+      return NextResponse.json({ jobs })
+    }
+
+    if (action === 'logs') {
+      const jobId = searchParams.get('job')
+      if (!jobId) {
+        return NextResponse.json({ error: 'Job ID required' }, { status: 400 })
+      }
+
+      // Find the job to get its state info
+      const cronFile = loadCronFile()
+      const job = cronFile?.jobs.find(j => j.id === jobId || j.name === jobId)
+
+      const logs: Array<{ timestamp: number; message: string; level: string }> = []
+
+      if (job?.state) {
+        if (job.state.lastRunAtMs) {
+          logs.push({
+            timestamp: job.state.lastRunAtMs,
+            message: `Job executed — status: ${job.state.lastStatus || 'unknown'}${job.state.lastDurationMs ? ` (${job.state.lastDurationMs}ms)` : ''}`,
+            level: job.state.lastStatus === 'error' || job.state.lastStatus === 'failed' ? 'error' : 'info',
+          })
+        }
+        if (job.state.lastError) {
+          logs.push({
+            timestamp: job.state.lastRunAtMs || Date.now(),
+            message: `Error: ${job.state.lastError}`,
+            level: 'error',
+          })
+        }
+        if (job.state.nextRunAtMs) {
+          logs.push({
+            timestamp: Date.now(),
+            message: `Next scheduled run: ${new Date(job.state.nextRunAtMs).toLocaleString()}`,
+            level: 'info',
+          })
+        }
+      }
+
+      return NextResponse.json({ logs })
+    }
+
+    return NextResponse.json({ error: 'Invalid action' }, { status: 400 })
+  } catch (error) {
+    console.error('Cron API error:', error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  try {
+    const body = await request.json()
+    const { action, jobName, jobId } = body
+
+    if (action === 'toggle') {
+      const id = jobId || jobName
+      if (!id) {
+        return NextResponse.json({ error: 'Job ID or name required' }, { status: 400 })
+      }
+
+      const cronFile = loadCronFile()
+      if (!cronFile) {
+        return NextResponse.json({ error: 'Cron file not found' }, { status: 404 })
+      }
+
+      const job = cronFile.jobs.find(j => j.id === id || j.name === id)
+      if (!job) {
+        return NextResponse.json({ error: 'Job not found' }, { status: 404 })
+      }
+
+      job.enabled = !job.enabled
+      job.updatedAtMs = Date.now()
+
+      if (!saveCronFile(cronFile)) {
+        return NextResponse.json({ error: 'Failed to save cron file' }, { status: 500 })
+      }
+
+      return NextResponse.json({ success: true, enabled: job.enabled })
+    }
+
+    if (action === 'trigger') {
+      const id = jobId || jobName
+      if (!id) {
+        return NextResponse.json({ error: 'Job ID required' }, { status: 400 })
+      }
+
+      if (process.env.MISSION_CONTROL_ALLOW_COMMAND_TRIGGER !== '1') {
+        return NextResponse.json(
+          { error: 'Manual triggers disabled. Set MISSION_CONTROL_ALLOW_COMMAND_TRIGGER=1 to enable.' },
+          { status: 403 }
+        )
+      }
+
+      const cronFile = loadCronFile()
+      const job = cronFile?.jobs.find(j => j.id === id || j.name === id)
+      if (!job) {
+        return NextResponse.json({ error: 'Job not found' }, { status: 404 })
+      }
+
+      // For OpenClaw cron jobs, trigger via the openclaw CLI
+      const { runCommand } = await import('@/lib/command')
+      try {
+        const { stdout, stderr } = await runCommand(config.openclawBin, [
+          'cron', 'trigger', job.id
+        ], { timeoutMs: 30000 })
+
+        return NextResponse.json({
+          success: true,
+          stdout: stdout.trim(),
+          stderr: stderr.trim()
+        })
+      } catch (execError: any) {
+        return NextResponse.json({
+          success: false,
+          error: execError.message,
+          stdout: execError.stdout?.trim() || '',
+          stderr: execError.stderr?.trim() || ''
+        }, { status: 500 })
+      }
+    }
+
+    if (action === 'remove') {
+      const id = jobId || jobName
+      if (!id) {
+        return NextResponse.json({ error: 'Job ID or name required' }, { status: 400 })
+      }
+
+      const cronFile = loadCronFile()
+      if (!cronFile) {
+        return NextResponse.json({ error: 'Cron file not found' }, { status: 404 })
+      }
+
+      const idx = cronFile.jobs.findIndex(j => j.id === id || j.name === id)
+      if (idx === -1) {
+        return NextResponse.json({ error: 'Job not found' }, { status: 404 })
+      }
+
+      cronFile.jobs.splice(idx, 1)
+
+      if (!saveCronFile(cronFile)) {
+        return NextResponse.json({ error: 'Failed to save cron file' }, { status: 500 })
+      }
+
+      return NextResponse.json({ success: true })
+    }
+
+    if (action === 'add') {
+      const { schedule, command, description } = body
+      const name = jobName || body.name
+      if (!schedule || !command || !name) {
+        return NextResponse.json(
+          { error: 'Schedule, command, and name required' },
+          { status: 400 }
+        )
+      }
+
+      const cronFile = loadCronFile() || { version: 1, jobs: [] }
+
+      const newJob: OpenClawCronJob = {
+        id: `mc-${Date.now().toString(36)}`,
+        agentId: String(process.env.MC_CRON_AGENT_ID || process.env.MC_COORDINATOR_AGENT || 'system'),
+        name,
+        enabled: true,
+        createdAtMs: Date.now(),
+        updatedAtMs: Date.now(),
+        schedule: {
+          kind: 'cron',
+          expr: schedule,
+        },
+        payload: {
+          kind: 'agentTurn',
+          message: command,
+        },
+        delivery: {
+          mode: 'none',
+        },
+        state: {},
+      }
+
+      cronFile.jobs.push(newJob)
+
+      if (!saveCronFile(cronFile)) {
+        return NextResponse.json({ error: 'Failed to save cron file' }, { status: 500 })
+      }
+
+      return NextResponse.json({ success: true })
+    }
+
+    return NextResponse.json({ error: 'Invalid action' }, { status: 400 })
+  } catch (error) {
+    console.error('Cron management error:', error)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}

src/app/api/events/route.ts

@@ -0,0 +1,65 @@
+import { eventBus, ServerEvent } from '@/lib/event-bus'
+
+export const dynamic = 'force-dynamic'
+export const runtime = 'nodejs'
+
+/**
+ * GET /api/events - Server-Sent Events stream for real-time DB mutations.
+ * Clients connect via EventSource and receive JSON-encoded events.
+ */
+export async function GET() {
+  const encoder = new TextEncoder()
+
+  // Cleanup function, set in start(), called in cancel()
+  let cleanup: (() => void) | null = null
+
+  const stream = new ReadableStream({
+    start(controller) {
+      // Send initial connection event
+      controller.enqueue(
+        encoder.encode(`data: ${JSON.stringify({ type: 'connected', data: null, timestamp: Date.now() })}\n\n`)
+      )
+
+      // Forward all server events to this SSE client
+      const handler = (event: ServerEvent) => {
+        try {
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(event)}\n\n`)
+          )
+        } catch {
+          // Client disconnected, cleanup will happen in cancel()
+        }
+      }
+
+      eventBus.on('server-event', handler)
+
+      // Heartbeat every 30s to keep connection alive through proxies
+      const heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(': heartbeat\n\n'))
+        } catch {
+          clearInterval(heartbeat)
+        }
+      }, 30_000)
+
+      cleanup = () => {
+        eventBus.off('server-event', handler)
+        clearInterval(heartbeat)
+      }
+    },
+
+    cancel() {
+      // Client disconnected
+      if (cleanup) cleanup()
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no', // Disable nginx buffering
+    },
+  })
+}

src/app/api/export/route.ts

@@ -0,0 +1,117 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { getDatabase, logAuditEvent } from '@/lib/db'
+
+/**
+ * GET /api/export?type=audit|tasks|activities|pipelines&format=csv|json&since=UNIX&until=UNIX
+ * Admin-only data export endpoint.
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const { searchParams } = new URL(request.url)
+  const type = searchParams.get('type')
+  const format = searchParams.get('format') || 'csv'
+  const since = searchParams.get('since')
+  const until = searchParams.get('until')
+
+  if (!type || !['audit', 'tasks', 'activities', 'pipelines'].includes(type)) {
+    return NextResponse.json(
+      { error: 'type required: audit, tasks, activities, pipelines' },
+      { status: 400 }
+    )
+  }
+
+  const db = getDatabase()
+  const conditions: string[] = []
+  const params: any[] = []
+
+  if (since) {
+    conditions.push('created_at >= ?')
+    params.push(parseInt(since))
+  }
+  if (until) {
+    conditions.push('created_at <= ?')
+    params.push(parseInt(until))
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+  let rows: any[] = []
+  let headers: string[] = []
+  let filename = ''
+
+  switch (type) {
+    case 'audit': {
+      rows = db.prepare(`SELECT * FROM audit_log ${where} ORDER BY created_at DESC`).all(...params)
+      headers = ['id', 'action', 'actor', 'actor_id', 'target_type', 'target_id', 'detail', 'ip_address', 'user_agent', 'created_at']
+      filename = 'audit-log'
+      break
+    }
+    case 'tasks': {
+      rows = db.prepare(`SELECT * FROM tasks ${where} ORDER BY created_at DESC`).all(...params)
+      headers = ['id', 'title', 'description', 'status', 'priority', 'assigned_to', 'created_by', 'created_at', 'updated_at', 'due_date', 'estimated_hours', 'actual_hours', 'tags']
+      filename = 'tasks'
+      break
+    }
+    case 'activities': {
+      rows = db.prepare(`SELECT * FROM activities ${where} ORDER BY created_at DESC`).all(...params)
+      headers = ['id', 'type', 'entity_type', 'entity_id', 'actor', 'description', 'data', 'created_at']
+      filename = 'activities'
+      break
+    }
+    case 'pipelines': {
+      rows = db.prepare(`SELECT pr.*, wp.name as pipeline_name FROM pipeline_runs pr LEFT JOIN workflow_pipelines wp ON pr.pipeline_id = wp.id ${where ? where.replace('created_at', 'pr.created_at') : ''} ORDER BY pr.created_at DESC`).all(...params)
+      headers = ['id', 'pipeline_id', 'pipeline_name', 'status', 'current_step', 'steps_snapshot', 'started_at', 'completed_at', 'triggered_by', 'created_at']
+      filename = 'pipeline-runs'
+      break
+    }
+  }
+
+  // Log the export
+  const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+  logAuditEvent({
+    action: 'data_export',
+    actor: auth.user.username,
+    actor_id: auth.user.id,
+    detail: { type, format, row_count: rows.length },
+    ip_address: ipAddress,
+  })
+
+  const dateStr = new Date().toISOString().split('T')[0]
+
+  if (format === 'csv') {
+    const csvRows = [headers.join(',')]
+    for (const row of rows) {
+      const values = headers.map(h => {
+        const val = row[h]
+        if (val == null) return ''
+        const str = String(val)
+        // Escape CSV: wrap in quotes if contains comma, newline, or quote
+        if (str.includes(',') || str.includes('\n') || str.includes('"')) {
+          return `"${str.replace(/"/g, '""')}"`
+        }
+        return str
+      })
+      csvRows.push(values.join(','))
+    }
+
+    return new NextResponse(csvRows.join('\n'), {
+      headers: {
+        'Content-Type': 'text/csv; charset=utf-8',
+        'Content-Disposition': `attachment; filename=${filename}-${dateStr}.csv`,
+      },
+    })
+  }
+
+  // JSON format
+  return NextResponse.json(
+    { type, exported_at: new Date().toISOString(), count: rows.length, data: rows },
+    {
+      headers: {
+        'Content-Disposition': `attachment; filename=${filename}-${dateStr}.json`,
+      },
+    }
+  )
+}

src/app/api/gateway-config/route.ts

@@ -0,0 +1,132 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { requireRole } from '@/lib/auth'
+import { logAuditEvent } from '@/lib/db'
+import { config } from '@/lib/config'
+import { join } from 'path'
+
+function getConfigPath(): string | null {
+  if (!config.openclawHome) return null
+  return join(config.openclawHome, 'openclaw.json')
+}
+
+/**
+ * GET /api/gateway-config - Read the gateway configuration
+ */
+export async function GET(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const configPath = getConfigPath()
+  if (!configPath) {
+    return NextResponse.json({ error: 'OPENCLAW_HOME not configured' }, { status: 404 })
+  }
+
+  try {
+    const { readFile } = require('fs/promises')
+    const raw = await readFile(configPath, 'utf-8')
+    const parsed = JSON.parse(raw)
+
+    // Redact sensitive fields for display
+    const redacted = redactSensitive(JSON.parse(JSON.stringify(parsed)))
+
+    return NextResponse.json({
+      path: configPath,
+      config: redacted,
+      raw_size: raw.length,
+    })
+  } catch (err: any) {
+    if (err.code === 'ENOENT') {
+      return NextResponse.json({ error: 'Config file not found', path: configPath }, { status: 404 })
+    }
+    return NextResponse.json({ error: `Failed to read config: ${err.message}` }, { status: 500 })
+  }
+}
+
+/**
+ * PUT /api/gateway-config - Update specific config fields
+ * Body: { updates: { "path.to.key": value, ... } }
+ *
+ * Uses dot-notation paths to set nested values.
+ * CRITICAL: Preserves gateway.auth.password and other sensitive fields.
+ */
+export async function PUT(request: NextRequest) {
+  const auth = requireRole(request, 'admin')
+  if ('error' in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const configPath = getConfigPath()
+  if (!configPath) {
+    return NextResponse.json({ error: 'OPENCLAW_HOME not configured' }, { status: 404 })
+  }
+
+  const body = await request.json().catch(() => null)
+  if (!body?.updates || typeof body.updates !== 'object') {
+    return NextResponse.json({ error: 'updates object required (dot-notation paths)' }, { status: 400 })
+  }
+
+  // Block writes to sensitive paths
+  const blockedPaths = ['gateway.auth.password', 'gateway.auth.secret']
+  for (const key of Object.keys(body.updates)) {
+    if (blockedPaths.some(bp => key.startsWith(bp))) {
+      return NextResponse.json({ error: `Cannot modify protected field: ${key}` }, { status: 403 })
+    }
+  }
+
+  try {
+    const { readFile, writeFile } = require('fs/promises')
+    const raw = await readFile(configPath, 'utf-8')
+    const parsed = JSON.parse(raw)
+
+    // Apply updates via dot-notation
+    const appliedKeys: string[] = []
+    for (const [dotPath, value] of Object.entries(body.updates)) {
+      setNestedValue(parsed, dotPath, value)
+      appliedKeys.push(dotPath)
+    }
+
+    // Write back with pretty formatting
+    await writeFile(configPath, JSON.stringify(parsed, null, 2) + '\n')
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || 'unknown'
+    logAuditEvent({
+      action: 'gateway_config_update',
+      actor: auth.user.username,
+      actor_id: auth.user.id,
+      detail: { updated_keys: appliedKeys },
+      ip_address: ipAddress,
+    })
+
+    return NextResponse.json({ updated: appliedKeys, count: appliedKeys.length })
+  } catch (err: any) {
+    return NextResponse.json({ error: `Failed to update config: ${err.message}` }, { status: 500 })
+  }
+}
+
+/** Set a value in a nested object using dot-notation path */
+function setNestedValue(obj: any, path: string, value: any) {
+  const keys = path.split('.')
+  let current = obj
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (current[keys[i]] === undefined) current[keys[i]] = {}
+    current = current[keys[i]]
+  }
+  current[keys[keys.length - 1]] = value
+}
+
+/** Redact sensitive values for display */
+function redactSensitive(obj: any, parentKey = ''): any {
+  if (typeof obj !== 'object' || obj === null) return obj
+
+  const sensitiveKeys = ['password', 'secret', 'token', 'api_key', 'apiKey']
+
+  for (const key of Object.keys(obj)) {
+    if (sensitiveKeys.some(sk => key.toLowerCase().includes(sk))) {
+      if (typeof obj[key] === 'string' && obj[key].length > 0) {
+        obj[key] = '••••••••'
+      }
+    } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+      redactSensitive(obj[key], key)
+    }
+  }
+
+  return obj
+}

src/app/api/gateways/health/route.ts

@@ -0,0 +1,85 @@
+import { NextRequest, NextResponse } from "next/server"
+import { requireRole } from "@/lib/auth"
+import { getDatabase } from "@/lib/db"
+
+interface GatewayEntry {
+  id: number
+  name: string
+  host: string
+  port: number
+  token: string
+  is_primary: number
+  status: string
+}
+
+interface HealthResult {
+  id: number
+  name: string
+  status: "online" | "offline" | "error"
+  latency: number | null
+  agents: string[]
+  sessions_count: number
+  error?: string
+}
+
+/**
+ * POST /api/gateways/health - Server-side health probe for all gateways
+ * Probes gateways from the server where loopback addresses are reachable.
+ */
+export async function POST(request: NextRequest) {
+  const auth = requireRole(request, "viewer")
+  if ("error" in auth) return NextResponse.json({ error: auth.error }, { status: auth.status })
+
+  const db = getDatabase()
+  const gateways = db.prepare("SELECT * FROM gateways ORDER BY is_primary DESC, name ASC").all() as GatewayEntry[]
+
+  const results: HealthResult[] = await Promise.all(
+    gateways.map(async (gw) => {
+      const start = Date.now()
+      try {
+        const controller = new AbortController()
+        const timeout = setTimeout(() => controller.abort(), 5000)
+
+        const probeUrl = "http://" + gw.host + ":" + gw.port + "/"
+        const res = await fetch(probeUrl, {
+          signal: controller.signal,
+        })
+        clearTimeout(timeout)
+
+        const latency = Date.now() - start
+        const status = res.ok ? "online" : "error"
+
+        db.prepare(
+          "UPDATE gateways SET status = ?, latency = ?, last_seen = (unixepoch()), updated_at = (unixepoch()) WHERE id = ?"
+        ).run(status, latency, gw.id)
+
+        return {
+          id: gw.id,
+          name: gw.name,
+          status: status as "online" | "error",
+          latency,
+          agents: [],
+          sessions_count: 0,
+        }
+      } catch (err: any) {
+        const latency = Date.now() - start
+
+        db.prepare(
+          "UPDATE gateways SET status = ?, latency = NULL, updated_at = (unixepoch()) WHERE id = ?"
+        ).run("offline", gw.id)
+
+        return {
+          id: gw.id,
+          name: gw.name,
+          status: "offline" as const,
+          latency: null,
+          agents: [],
+          sessions_count: 0,
+          error: err.name === "AbortError" ? "timeout" : (err.message || "connection failed"),
+        }
+      }
+    })
+  )
+
+  return NextResponse.json({ results, probed_at: Date.now() })
+}