/` 形式的短链接。短链 code 只在创建时返回，数据库只保存 hash；访问时由 ClawManager 解析短链，再复用现有实例代理链路转发到对应 Lite gateway 或 Pro service。当前支持普通分享链接和密码访问，并支持固定时间、自定义时间和永久有效几类过期策略。
+
+## Lite / Pro 架构图
+
+```mermaid
+flowchart LR
+ user["用户 / 外部访问者"] --> web["ClawManager Web"]
+ user --> shortLink["Share Link
/s/<code>/"]
+
+ web --> api["ClawManager Backend API"]
+ shortLink --> publicAccess["短链解析与鉴权
Share Link / Password"]
+ publicAccess --> proxy["统一实例代理"]
+ api --> instanceService["Instance Service
instance_mode: lite / pro"]
+ instanceService --> mode{"实例模式"}
+
+ mode -->|Lite| liteScheduler["Lite Scheduler
runtime_type = gateway"]
+ mode -->|Pro| proLifecycle["Pro Lifecycle
runtime_type = desktop"]
+
+ liteScheduler --> runtimePod["共享 Runtime Pod"]
+ runtimePod --> runtimeAgent["Runtime Pod Agent V2"]
+ runtimeAgent --> gatewayA["Gateway 进程
Lite 实例 A"]
+ runtimeAgent --> gatewayB["Gateway 进程
Lite 实例 B"]
+ runtimeAgent --> gatewayN["Gateway 进程
Lite 实例 N"]
+
+ proLifecycle --> deployment["专属 Deployment"]
+ deployment --> service["专属 Service"]
+ deployment --> pvc["专属 PVC"]
+ service --> desktop["Desktop Runtime
Pro 实例"]
+
+ proxy -->|Lite| gatewayA
+ proxy -->|Lite| gatewayB
+ proxy -->|Pro| service
+
+ team["Team 创建"] --> teamService["Team Service"]
+ teamService --> teamMemberMode{"成员实例模式"}
+ teamMemberMode -->|Lite 成员| liteScheduler
+ teamMemberMode -->|Pro 成员| proLifecycle
+
+ aiGateway["AI Gateway / 审计 / 费用 / 风险"] --> attribution["实例归因
instance_id / instance_mode / runtime_type"]
+ gatewayA --> attribution
+ gatewayB --> attribution
+ desktop --> attribution
+```
+
+## 目标
+
+- 新增 Lite 实例模式，让用户在创建普通实例时可以选择 Lite / Pro。
+- 保留 Pro 模式的完整桌面实例能力，同时让 Lite 模式复用共享运行时，降低资源占用和启动成本。
+- 将 Lite / Pro 模式贯通到 Team 场景，让 Team 成员实例也可以按角色选择 Lite 或 Pro。
+- 增加 Share Link 能力，支持将实例访问入口分享给外部用户。
+- 建立自动化测试覆盖，保证普通实例、Team 实例和分享访问能力可以持续回归。
+
+## 进展
+
+- 普通实例创建已经支持 Lite / Pro 模式选择。
+- Lite 实例创建时会进入共享 gateway runtime 链路，Pro 实例创建时会进入独立 desktop runtime 链路。
+- 前端创建页、实例详情页、实例列表和管理端已完成 Lite / Pro 的展示和交互区分。
+- Lite 模式下已简化资源配置流程，不再要求用户配置专属 CPU、内存、存储和 GPU；Pro 模式继续保留专属资源配置能力。
+- Team 创建流程已经支持为成员选择 Lite / Pro 实例模式。
+- Team 成员实例已能按选择的模式创建，并保留后续接入 Team 协作链路所需的基础配置。
+- Share Link 已完成基础能力，包括短链接分享、密码访问、过期时间选择和复制入口。
+- Share Link 访问已统一走 ClawManager 代理，能够兼容 Lite gateway 和 Pro service 两种后端形态。
+- 相关改动已部署到 172.16.1.12 环境，并完成一轮自动化回归。
+- 当前自动化测试已覆盖普通实例 Lite / Pro 模式、Share Link 基础行为、管理端模式展示以及 Team Lite 创建链路。
+- 联调中发现，部分 Lite runtime / agent 能力仍需补齐，主要集中在 Team 任务消费和 Hermes Lite 会话稳定性上。
+
+## 计划
+
+- 继续推进 agent / runtime 侧补齐 Lite 模式能力，重点包括 Team 任务接收、执行状态回写和会话稳定性。
+- 在 agent / runtime 修复后，补充完整的 Team Lite 任务执行 e2e，覆盖从建队、成员实例创建、任务下发到状态回写的闭环。
+- 继续完善 Hermes Lite 的联调验证，确保 Lite 模式下聊天、访问和实例生命周期稳定。
+- 对 Share Link 增加更完整的回归覆盖，包括短链访问、密码访问、过期策略、禁用/重新生成等场景。
+- 在 172.16.1.12 环境继续做端到端回归，确认普通实例、Team 实例和 Share Link 在 Lite / Pro 两种模式下都能稳定运行。
+- 最后整理验收说明，明确 Lite / Pro 的支持范围、已验证场景和仍需 agent 侧配合的事项。
+
+## 简短汇报口径
+
+这次开发不是单独做 Team Lite，而是把实例模式整体升级为 Lite / Pro 两种形态。Lite 走共享 runtime gateway，Pro 走独立 desktop runtime，对用户层统一暴露 Lite / Pro，对后端仍按不同 runtime backend 调度。
+
+目前普通实例创建、实例展示、管理端识别、Team 成员创建以及 Share Link 分享能力都已经完成基础支持，并已在 172.16.1.12 做了一轮自动化回归。后续重点是继续和 agent / runtime 侧联调，补齐 Lite 模式下 Team 任务执行闭环和 Hermes Lite 会话稳定性，然后补充更完整的端到端验收测试。
diff --git a/docs/openclaw-windows-node-exec.md b/docs/openclaw-windows-node-exec.md
new file mode 100644
index 0000000..5cee925
--- /dev/null
+++ b/docs/openclaw-windows-node-exec.md
@@ -0,0 +1,233 @@
+# OpenClaw Gateway + Windows Node Exec Configuration
+
+本文说明一个常见 ClawManager 使用场景：
+
+```text
+用户浏览器
+ -> ClawManager Web / OpenClaw WebChat
+ -> 服务端 OpenClaw 实例里的 Gateway
+ -> 本机 Windows 上运行的 OpenClaw node
+ -> 在 Windows 本机执行 system.run / system.which
+```
+
+目标是：用户访问 ClawManager 创建出的 OpenClaw 实例 Web UI，在聊天中让 Agent 操作个人 Windows 电脑上的命令或自动化任务。
+
+## 1. 基本判断
+
+这个场景可行，但要区分两类授权：
+
+| 授权类型 | 作用 | 是否每次变化 |
+| --- | --- | --- |
+| Device pairing | 允许 Windows node 接入服务端 Gateway | 通常只需要一次 |
+| Exec approval | 允许某条 `system.run` 在 Windows node 上执行 | ask 模式下每条命令都会生成新的 requestId |
+
+如果错误是：
+
+```json
+{
+ "status": "error",
+ "tool": "exec",
+ "error": "UNAVAILABLE: SYSTEM_RUN_DENIED: approval required"
+}
+```
+
+说明链路已经打到 Windows node，问题不是网络，而是 `system.run` 被 Windows node 的 exec approval 策略拦住。
+
+## 2. 前置条件
+
+服务端 OpenClaw 实例里的 Gateway 必须满足：
+
+- Gateway WebSocket 端口能被 Windows 电脑访问，例如 `192.168.30.133:31889`。
+- Gateway 不能只监听容器内 `127.0.0.1`。
+- 如果使用明文 `ws://`，建议只在内网、VPN、Tailscale 或 SSH tunnel 内使用。
+- Windows node 需要拿到 Gateway 的认证 token 或 password。
+
+Windows 本机需要满足：
+
+- 已安装 OpenClaw CLI。
+- 能访问服务端 Gateway 地址和端口。
+- Node 进程能持久运行，建议调通后改为 service 模式。
+
+## 3. 启动 Windows Node
+
+在服务端 OpenClaw 实例里查看 Gateway token：
+
+```bash
+openclaw config get gateway.auth.token
+```
+
+在 Windows PowerShell 中设置 token 并启动 node：
+
+```powershell
+$env:OPENCLAW_GATEWAY_TOKEN=""
+openclaw node run --host 192.168.30.133 --port 31889 --display-name "windows-node"
+```
+
+如果要后台常驻：
+
+```powershell
+$env:OPENCLAW_GATEWAY_TOKEN=""
+openclaw node install --host 192.168.30.133 --port 31889 --display-name "windows-node" --force
+openclaw node restart
+openclaw node status
+```
+
+如果 Gateway 使用 TLS，再加：
+
+```powershell
+openclaw node run --host 192.168.30.133 --port 31889 --tls --display-name "windows-node"
+```
+
+## 4. 在 Gateway 侧完成 Node Pairing
+
+进入服务端 OpenClaw 实例终端，查看待审批设备：
+
+```bash
+openclaw devices list
+```
+
+找到 role 为 `node` 的请求，批准最新的 `requestId`：
+
+```bash
+openclaw devices approve
+```
+
+确认 node 已连接并 paired：
+
+```bash
+openclaw nodes status
+openclaw nodes describe --node "windows-node"
+```
+
+如果 `devices list` 每次看到新的 pairing `requestId`，通常说明 node 身份或认证信息变化了。优先检查：
+
+- Windows 上是否反复使用了不同的 `--node-id`。
+- Windows 上 `~/.openclaw/node.json` 是否被删除或重建。
+- Gateway token/password 是否变更。
+- Node 是否确实使用同一个 `OPENCLAW_GATEWAY_TOKEN` 启动。
+
+## 5. 将 Exec 指向 Windows Node
+
+在服务端 OpenClaw 实例里配置默认 exec host：
+
+```bash
+openclaw config set tools.exec.host node
+openclaw config set tools.exec.node "windows-node"
+```
+
+如果有多个 Agent，也可以按 Agent 配置：
+
+```bash
+openclaw config get agents.list
+openclaw config set agents.list[0].tools.exec.node "windows-node"
+```
+
+## 6. Exec Approval 配置方案
+
+### 方案 A：稳定自动化，免审批执行
+
+仅建议在完全可信的内网或 VPN 环境中使用。
+
+服务端 Gateway 请求策略：
+
+```bash
+openclaw config set tools.exec.security full
+openclaw config set tools.exec.ask off
+openclaw gateway restart
+```
+
+同时把 Windows node 本地 approvals 策略也打开：
+
+```bash
+openclaw approvals set --node "windows-node" --stdin <<'EOF'
+{
+ "version": 1,
+ "defaults": {
+ "security": "full",
+ "ask": "off",
+ "askFallback": "full"
+ }
+}
+EOF
+```
+
+注意：只改 `tools.exec.*` 不够。OpenClaw 会取 Gateway 请求策略和 node 本地 `~/.openclaw/exec-approvals.json` 中更严格的一方。如果 node 本地仍是 `ask: "always"` 或 `askFallback: "deny"`，还是会继续提示授权。
+
+### 方案 B：更安全，使用 allowlist
+
+服务端 Gateway 请求策略：
+
+```bash
+openclaw config set tools.exec.security allowlist
+openclaw config set tools.exec.ask off
+openclaw gateway restart
+```
+
+给 Windows node 添加允许执行的命令：
+
+```bash
+openclaw approvals allowlist add --agent "*" --node "windows-node" "powershell.exe"
+openclaw approvals allowlist add --agent "*" --node "windows-node" "pwsh.exe"
+openclaw approvals allowlist add --agent "*" --node "windows-node" "cmd.exe"
+```
+
+更推荐只放行具体脚本或具体工具，例如：
+
+```bash
+openclaw approvals allowlist add --agent "*" --node "windows-node" "C:\\Tools\\automation\\daily-task.ps1"
+openclaw approvals allowlist add --agent "*" --node "windows-node" "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+```
+
+Windows 上如果命令被包装成 `cmd.exe /c ...`，allowlist 模式下仍可能需要审批。这是 OpenClaw 的安全行为。若需要完全无提示自动化，使用方案 A。
+
+## 7. 验证
+
+在服务端 OpenClaw 实例里执行：
+
+```bash
+openclaw nodes status
+openclaw nodes describe --node "windows-node"
+openclaw approvals get --node "windows-node"
+```
+
+然后在 WebChat 里让 Agent 执行一个简单命令：
+
+```text
+请在 node 上执行 hostname，并告诉我输出。
+```
+
+如果仍然报 `SYSTEM_RUN_DENIED`：
+
+1. 确认 `openclaw nodes status` 中 node 是 connected/paired。
+2. 确认 `openclaw nodes describe --node "windows-node"` 中包含 `system.run`。
+3. 确认 `openclaw approvals get --node "windows-node"` 的 effective policy 是预期值。
+4. 如果 effective policy 仍然是 ask 或 deny，说明 node 本地 approvals 文件没有被更新。
+5. 如果是 allowlist miss，说明命令没有命中 allowlist，改成 full 或补 allowlist。
+
+## 8. requestId 每次不同怎么处理
+
+如果 requestId 来自 `devices list`：
+
+- 这是 node pairing 请求。
+- 应该只需要批准一次。
+- 如果每次都变，说明 node 身份被重置或认证信息变化。
+
+如果 requestId 来自 exec approval：
+
+- 这是命令执行审批。
+- 每条新命令都有自己的 requestId，变化是正常现象。
+- 要避免反复授权，需要配置 `tools.exec.ask off`，并同步配置 node 本地 approvals。
+
+## 9. 安全建议
+
+- 不要把 Gateway WebSocket 端口直接暴露公网。
+- 生产环境优先使用 VPN、Tailscale、WireGuard 或 SSH tunnel。
+- 如果只是做固定自动化，优先使用 allowlist 放行具体脚本。
+- `security full + ask off` 相当于允许 WebChat 控制 Windows 本机命令，只有在完全可信环境使用。
+- 定期检查 Windows node 的 `~/.openclaw/exec-approvals.json`。
+- 不再使用时，及时停掉 node：
+
+```powershell
+openclaw node stop
+openclaw node uninstall
+```
diff --git a/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md b/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md
new file mode 100644
index 0000000..2ff15ef
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-01-clawmanager-v2-runtime-pool.md
@@ -0,0 +1,3080 @@
+# ClawManager V2 Runtime Pool Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build ClawManager V2 so OpenClaw and Hermes instances run as gateway processes inside shared runtime Pods, with workspace isolation, fast failover, admin runtime observability, and a simpler user UI.
+
+**Architecture:** The backend remains the source of truth in MySQL, uses Redis for hot locks/events/cache, and runs an embedded leader-elected runtime scheduler across multiple backend replicas. Runtime Pods are managed by Kubernetes Deployments and `clawmanager-agent`; each runtime Pod hosts up to 100 gateways and exposes gateway traffic by Pod IP plus assigned port. Workspaces live under a shared `/workspaces` mount and are accessed through a dedicated backend file manager API, not through the frame.
+
+**Tech Stack:** Go 1.26, Gin, MySQL via `upper/db`, Redis RESP client, Kubernetes client-go, React 19, Vite, TypeScript, Tailwind CSS, Kubernetes YAML.
+
+---
+
+## Scope Check
+
+This release touches several subsystems, but they are tightly ordered: schema first, scheduler second, lifecycle/proxy/files third, UI and manifests last. Keep the work in this single master plan, but commit after each task so any subsystem can be reviewed independently.
+
+## File Structure
+
+Backend data and migrations:
+- Modify: `backend/internal/db/migrations.go` - existing embedded migration runner remains unchanged unless ordering assumptions fail in tests.
+- Create: `backend/internal/db/migrations/023_add_runtime_pool_v2.sql` - runtime Pod, gateway binding, rollout, and workspace audit schema.
+- Modify: `backend/internal/db/migrations_test.go` - verify migration file ordering and SQL splitting still handles migration 023.
+- Modify: `backend/internal/models/instance.go` - add workspace fields and V2 runtime metadata.
+- Create: `backend/internal/models/runtime_pod.go` - runtime Pod state and metrics model.
+- Create: `backend/internal/models/instance_runtime_binding.go` - active gateway binding model.
+- Create: `backend/internal/models/runtime_rollout.go` - rollout state model for gray upgrades.
+- Create: `backend/internal/models/workspace_file_audit.go` - upload/download/write audit model.
+- Modify: `backend/internal/repository/instance_repository.go` - V2 lifecycle selectors and status update helpers.
+- Create: `backend/internal/repository/runtime_pod_repository.go` - runtime Pod CRUD and capacity claims.
+- Create: `backend/internal/repository/instance_runtime_binding_repository.go` - gateway binding CRUD and generation-safe updates.
+- Create: `backend/internal/repository/runtime_rollout_repository.go` - rollout CRUD and selectors.
+- Create: `backend/internal/repository/workspace_file_audit_repository.go` - append-only file audit writes.
+
+Backend runtime scheduling and agent integration:
+- Create: `docs/clawmanager-agent-v2-contract.md` - exact HTTP dual-channel contract required from `clawmanager-agent`.
+- Create: `backend/internal/services/redis_client.go` - platform Redis client reusing the existing RESP approach.
+- Create: `backend/internal/services/runtime_agent_client.go` - backend-to-agent command client.
+- Create: `backend/internal/services/runtime_scheduler.go` - leader loop, assignment, failover, and gray-drain orchestration.
+- Create: `backend/internal/services/runtime_capacity.go` - capacity calculations and runtime type normalization.
+- Create: `backend/internal/services/runtime_events.go` - Redis-backed runtime event fanout for all backend replicas.
+- Create: `backend/internal/services/runtime_leader.go` - Kubernetes Lease leader election wrapper.
+- Create: `backend/internal/services/k8s/runtime_deployment_service.go` - create, scale, and inspect OpenClaw/Hermes runtime Deployments.
+- Modify: `backend/internal/services/instance_service.go` - route V2 create/start/stop/delete through scheduler state; keep legacy behavior for old instance types.
+- Modify: `backend/internal/services/instance_proxy_service.go` - proxy V2 instances to binding Pod IP plus gateway port; keep legacy service proxy fallback.
+- Modify: `backend/internal/services/sync_service.go` - stop assuming every running instance owns a Pod.
+- Modify: `backend/cmd/server/main.go` - wire repositories, services, scheduler start, routes, and websocket runtime event bridge.
+
+Backend workspace file APIs:
+- Create: `backend/internal/services/workspace_path_guard.go` - path clean, realpath, and symlink escape prevention.
+- Create: `backend/internal/services/workspace_file_service.go` - list, preview, download, upload, mkdir, rename, delete.
+- Create: `backend/internal/handlers/workspace_file_handler.go` - user-facing workspace file endpoints.
+- Modify: `backend/internal/handlers/instance_handler.go` - attach workspace routes and simplify status response for V2.
+- Modify: `backend/internal/utils/response.go` - add V2 file validation errors to client-safe bad request mapping.
+
+Backend admin APIs:
+- Create: `backend/internal/handlers/runtime_pool_handler.go` - admin runtime Pod status, metrics, drain, and rollout endpoints.
+- Modify: `backend/internal/services/websocket_service.go` - add admin runtime event subscriptions with user-role checks.
+- Modify: `backend/internal/handlers/websocket_handler.go` if it exists in this repository; otherwise wire websocket changes in the existing handler file discovered during implementation.
+
+Frontend user and admin experience:
+- Modify: `frontend/package.json` and lock file - add `lucide-react` if icons are not already available.
+- Modify: `frontend/src/index.css` - neutral, simple design tokens; remove heavy gradients and oversized radii.
+- Modify: `frontend/src/components/UserLayout.tsx` - simpler user shell.
+- Modify: `frontend/src/components/AdminLayout.tsx` - simpler admin shell and add Runtime Pods navigation.
+- Modify: `frontend/src/types/instance.ts` - V2 instance availability and workspace types.
+- Create: `frontend/src/types/runtimePool.ts` - admin runtime Pod, gateway, metrics, rollout types.
+- Create: `frontend/src/services/workspaceService.ts` - workspace API client.
+- Create: `frontend/src/services/runtimePoolService.ts` - admin runtime API client.
+- Modify: `frontend/src/hooks/useWebSocket.ts` - add admin runtime event hook.
+- Modify: `frontend/src/services/instanceService.ts` - V2 status fields and workspace entry points.
+- Modify: `frontend/src/pages/instances/CreateInstancePage.tsx` - only allow creating OpenClaw and Hermes for V2.
+- Modify: `frontend/src/pages/instances/InstanceListPage.tsx` - hide Pod/service/resource details from ordinary users.
+- Modify: `frontend/src/pages/instances/InstanceDetailPage.tsx` - show availability, service frame, workspace file manager, and simple controls.
+- Create: `frontend/src/components/WorkspaceFileManager.tsx` - independent file list, preview, upload, download, rename, delete.
+- Create: `frontend/src/components/InstanceServiceFrame.tsx` - OpenClaw/Hermes iframe wrapper with availability state.
+- Create: `frontend/src/pages/admin/RuntimePodsPage.tsx` - admin-only runtime Pod metrics and gateway usage.
+- Modify: `frontend/src/pages/admin/SystemSettingsPage.tsx` - add OpenClaw/Hermes runtime image and gray rollout controls.
+- Modify: `frontend/src/router/index.tsx` - route `/admin/runtime-pods`.
+
+Deployment:
+- Modify: `deployments/k8s/clawmanager.yaml` - one-YAML install for Redis, workspace store, backend replicas, runtime Deployments, RBAC, env.
+- Modify: `deployments/k3s/clawmanager.yaml` - same defaults adapted to k3s/local path storage.
+- Modify: `backend/deployments/k8s/clawreef-incluster.yaml` if this file is still shipped as an install path; otherwise leave it unchanged and document that `deployments/k8s/clawmanager.yaml` is canonical.
+
+## Agent Contract Summary
+
+The `clawmanager-agent` changes are documented but implemented outside this repository. The backend implementation must assume these endpoints and payloads:
+
+Agent-to-backend channel:
+
+```http
+POST /api/v1/runtime-agent/register
+POST /api/v1/runtime-agent/heartbeat
+POST /api/v1/runtime-agent/gateways/report
+POST /api/v1/runtime-agent/skills/report
+POST /api/v1/runtime-agent/metrics/report
+```
+
+Backend-to-agent channel:
+
+```http
+GET http://{pod_ip}:19090/v1/health
+GET http://{pod_ip}:19090/v1/metrics
+POST http://{pod_ip}:19090/v1/gateways
+DELETE http://{pod_ip}:19090/v1/gateways/{gateway_id}
+POST http://{pod_ip}:19090/v1/gateways/{gateway_id}/health
+POST http://{pod_ip}:19090/v1/drain
+```
+
+Gateway create request:
+
+```json
+{
+ "instance_id": 123,
+ "user_id": 45,
+ "agent_type": "openclaw",
+ "workspace_path": "/workspaces/openclaw/user-45/instance-123",
+ "port_range": { "start": 20000, "end": 20099 },
+ "uid": 200123,
+ "gid": 200123,
+ "cpu_cores": 2,
+ "memory_mb": 4096,
+ "disk_quota_mb": 20480,
+ "generation": 7
+}
+```
+
+Gateway create response:
+
+```json
+{
+ "gateway_id": "gw-123-7",
+ "port": 20017,
+ "pid": 8842,
+ "status": "running"
+}
+```
+
+The agent must allocate a free port inside `20000-20099`, enforce one Linux UID/GID per instance using `200000 + instance_id`, apply cgroup CPU/memory limits, enforce workspace quota, reject symlink escapes inside workspaces, report gateway health, and survive backend replica changes. During gray upgrade, `POST /v1/drain` must reject new gateways and continue reporting existing gateway health until ClawManager migrates them away.
+
+## Task 1: Schema, Models, And Repository Interfaces
+
+**Files:**
+- Create: `backend/internal/db/migrations/023_add_runtime_pool_v2.sql`
+- Modify: `backend/internal/db/migrations_test.go`
+- Modify: `backend/internal/models/instance.go`
+- Create: `backend/internal/models/runtime_pod.go`
+- Create: `backend/internal/models/instance_runtime_binding.go`
+- Create: `backend/internal/models/runtime_rollout.go`
+- Create: `backend/internal/models/workspace_file_audit.go`
+- Modify: `backend/internal/repository/instance_repository.go`
+- Create: `backend/internal/repository/runtime_pod_repository.go`
+- Create: `backend/internal/repository/instance_runtime_binding_repository.go`
+- Create: `backend/internal/repository/runtime_rollout_repository.go`
+- Create: `backend/internal/repository/workspace_file_audit_repository.go`
+
+- [ ] **Step 1: Add failing migration order test**
+
+Append this test to `backend/internal/db/migrations_test.go`:
+
+```go
+func TestMigration023IsEmbedded(t *testing.T) {
+ files, err := migrationFiles.ReadDir("migrations")
+ if err != nil {
+ t.Fatalf("read embedded migrations: %v", err)
+ }
+
+ found := false
+ for _, file := range files {
+ if file.Name() == "023_add_runtime_pool_v2.sql" {
+ found = true
+ break
+ }
+ }
+ if !found {
+ t.Fatalf("migration 023_add_runtime_pool_v2.sql is not embedded")
+ }
+}
+```
+
+- [ ] **Step 2: Run migration test and verify it fails**
+
+Run:
+
+```powershell
+go test ./backend/internal/db -run TestMigration023IsEmbedded -count=1
+```
+
+Expected: fail with `migration 023_add_runtime_pool_v2.sql is not embedded`.
+
+- [ ] **Step 3: Create migration 023**
+
+Create `backend/internal/db/migrations/023_add_runtime_pool_v2.sql` with:
+
+```sql
+ALTER TABLE instances
+ ADD COLUMN workspace_path VARCHAR(1024) NULL AFTER mount_path,
+ ADD COLUMN workspace_usage_bytes BIGINT NOT NULL DEFAULT 0 AFTER workspace_path,
+ ADD COLUMN runtime_generation INT NOT NULL DEFAULT 1 AFTER workspace_usage_bytes,
+ ADD COLUMN runtime_error_message TEXT NULL AFTER runtime_generation;
+
+CREATE TABLE runtime_pods (
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
+ runtime_type VARCHAR(32) NOT NULL,
+ namespace VARCHAR(128) NOT NULL,
+ pod_name VARCHAR(255) NOT NULL,
+ pod_uid VARCHAR(128) NULL,
+ pod_ip VARCHAR(64) NULL,
+ node_name VARCHAR(255) NULL,
+ deployment_name VARCHAR(255) NOT NULL,
+ image_ref VARCHAR(512) NOT NULL,
+ agent_endpoint VARCHAR(255) NULL,
+ state VARCHAR(32) NOT NULL DEFAULT 'pending',
+ capacity INT NOT NULL DEFAULT 100,
+ used_slots INT NOT NULL DEFAULT 0,
+ draining TINYINT(1) NOT NULL DEFAULT 0,
+ cpu_millis_used BIGINT NOT NULL DEFAULT 0,
+ memory_bytes_used BIGINT NOT NULL DEFAULT 0,
+ disk_bytes_used BIGINT NOT NULL DEFAULT 0,
+ network_rx_bytes BIGINT NOT NULL DEFAULT 0,
+ network_tx_bytes BIGINT NOT NULL DEFAULT 0,
+ metrics_json JSON NULL,
+ last_seen_at DATETIME NULL,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+ UNIQUE KEY uk_runtime_pod_namespace_name (namespace, pod_name),
+ KEY idx_runtime_pods_schedulable (runtime_type, state, draining, used_slots, capacity),
+ KEY idx_runtime_pods_last_seen (last_seen_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE instance_runtime_bindings (
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
+ instance_id INT NOT NULL,
+ runtime_pod_id BIGINT NOT NULL,
+ runtime_type VARCHAR(32) NOT NULL,
+ gateway_id VARCHAR(128) NOT NULL,
+ gateway_port INT NOT NULL,
+ gateway_pid INT NULL,
+ workspace_path VARCHAR(1024) NOT NULL,
+ state VARCHAR(32) NOT NULL DEFAULT 'creating',
+ generation INT NOT NULL DEFAULT 1,
+ last_health_at DATETIME NULL,
+ error_message TEXT NULL,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+ UNIQUE KEY uk_instance_runtime_binding_instance (instance_id),
+ UNIQUE KEY uk_instance_runtime_binding_gateway (runtime_pod_id, gateway_port),
+ KEY idx_instance_runtime_binding_pod_state (runtime_pod_id, state),
+ CONSTRAINT fk_instance_runtime_binding_instance
+ FOREIGN KEY (instance_id) REFERENCES instances(id) ON DELETE CASCADE,
+ CONSTRAINT fk_instance_runtime_binding_pod
+ FOREIGN KEY (runtime_pod_id) REFERENCES runtime_pods(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE runtime_rollouts (
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
+ runtime_type VARCHAR(32) NOT NULL,
+ target_image_ref VARCHAR(512) NOT NULL,
+ status VARCHAR(32) NOT NULL DEFAULT 'pending',
+ batch_size INT NOT NULL DEFAULT 1,
+ max_unavailable INT NOT NULL DEFAULT 1,
+ started_by INT NULL,
+ started_at DATETIME NULL,
+ finished_at DATETIME NULL,
+ error_message TEXT NULL,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+ KEY idx_runtime_rollouts_type_status (runtime_type, status)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE workspace_file_audits (
+ id BIGINT PRIMARY KEY AUTO_INCREMENT,
+ instance_id INT NOT NULL,
+ user_id INT NOT NULL,
+ action VARCHAR(32) NOT NULL,
+ relative_path VARCHAR(1024) NOT NULL,
+ bytes BIGINT NOT NULL DEFAULT 0,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ KEY idx_workspace_file_audits_instance_time (instance_id, created_at),
+ KEY idx_workspace_file_audits_user_time (user_id, created_at),
+ CONSTRAINT fk_workspace_file_audits_instance
+ FOREIGN KEY (instance_id) REFERENCES instances(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+- [ ] **Step 4: Extend instance model**
+
+Add fields to `backend/internal/models/instance.go` after `MountPath` and after `StoppedAt`:
+
+```go
+ WorkspacePath *string `db:"workspace_path" json:"workspace_path,omitempty"`
+ WorkspaceUsageBytes int64 `db:"workspace_usage_bytes" json:"workspace_usage_bytes"`
+ RuntimeGeneration int `db:"runtime_generation" json:"runtime_generation"`
+ RuntimeErrorMessage *string `db:"runtime_error_message" json:"runtime_error_message,omitempty"`
+```
+
+- [ ] **Step 5: Add runtime models**
+
+Create `backend/internal/models/runtime_pod.go`:
+
+```go
+package models
+
+import "time"
+
+type RuntimePod struct {
+ ID int64 `db:"id,primarykey,autoincrement" json:"id"`
+ RuntimeType string `db:"runtime_type" json:"runtime_type"`
+ Namespace string `db:"namespace" json:"namespace"`
+ PodName string `db:"pod_name" json:"pod_name"`
+ PodUID *string `db:"pod_uid" json:"pod_uid,omitempty"`
+ PodIP *string `db:"pod_ip" json:"pod_ip,omitempty"`
+ NodeName *string `db:"node_name" json:"node_name,omitempty"`
+ DeploymentName string `db:"deployment_name" json:"deployment_name"`
+ ImageRef string `db:"image_ref" json:"image_ref"`
+ AgentEndpoint *string `db:"agent_endpoint" json:"agent_endpoint,omitempty"`
+ State string `db:"state" json:"state"`
+ Capacity int `db:"capacity" json:"capacity"`
+ UsedSlots int `db:"used_slots" json:"used_slots"`
+ Draining bool `db:"draining" json:"draining"`
+ CPUMillisUsed int64 `db:"cpu_millis_used" json:"cpu_millis_used"`
+ MemoryBytesUsed int64 `db:"memory_bytes_used" json:"memory_bytes_used"`
+ DiskBytesUsed int64 `db:"disk_bytes_used" json:"disk_bytes_used"`
+ NetworkRXBytes int64 `db:"network_rx_bytes" json:"network_rx_bytes"`
+ NetworkTXBytes int64 `db:"network_tx_bytes" json:"network_tx_bytes"`
+ MetricsJSON *string `db:"metrics_json" json:"metrics_json,omitempty"`
+ LastSeenAt *time.Time `db:"last_seen_at" json:"last_seen_at,omitempty"`
+ CreatedAt time.Time `db:"created_at" json:"created_at"`
+ UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
+}
+
+func (RuntimePod) TableName() string {
+ return "runtime_pods"
+}
+```
+
+Create `backend/internal/models/instance_runtime_binding.go`:
+
+```go
+package models
+
+import "time"
+
+type InstanceRuntimeBinding struct {
+ ID int64 `db:"id,primarykey,autoincrement" json:"id"`
+ InstanceID int `db:"instance_id" json:"instance_id"`
+ RuntimePodID int64 `db:"runtime_pod_id" json:"runtime_pod_id"`
+ RuntimeType string `db:"runtime_type" json:"runtime_type"`
+ GatewayID string `db:"gateway_id" json:"gateway_id"`
+ GatewayPort int `db:"gateway_port" json:"gateway_port"`
+ GatewayPID *int `db:"gateway_pid" json:"gateway_pid,omitempty"`
+ WorkspacePath string `db:"workspace_path" json:"workspace_path"`
+ State string `db:"state" json:"state"`
+ Generation int `db:"generation" json:"generation"`
+ LastHealthAt *time.Time `db:"last_health_at" json:"last_health_at,omitempty"`
+ ErrorMessage *string `db:"error_message" json:"error_message,omitempty"`
+ CreatedAt time.Time `db:"created_at" json:"created_at"`
+ UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
+}
+
+func (InstanceRuntimeBinding) TableName() string {
+ return "instance_runtime_bindings"
+}
+```
+
+Create `backend/internal/models/runtime_rollout.go`:
+
+```go
+package models
+
+import "time"
+
+type RuntimeRollout struct {
+ ID int64 `db:"id,primarykey,autoincrement" json:"id"`
+ RuntimeType string `db:"runtime_type" json:"runtime_type"`
+ TargetImageRef string `db:"target_image_ref" json:"target_image_ref"`
+ Status string `db:"status" json:"status"`
+ BatchSize int `db:"batch_size" json:"batch_size"`
+ MaxUnavailable int `db:"max_unavailable" json:"max_unavailable"`
+ StartedBy *int `db:"started_by" json:"started_by,omitempty"`
+ StartedAt *time.Time `db:"started_at" json:"started_at,omitempty"`
+ FinishedAt *time.Time `db:"finished_at" json:"finished_at,omitempty"`
+ ErrorMessage *string `db:"error_message" json:"error_message,omitempty"`
+ CreatedAt time.Time `db:"created_at" json:"created_at"`
+ UpdatedAt time.Time `db:"updated_at" json:"updated_at"`
+}
+
+func (RuntimeRollout) TableName() string {
+ return "runtime_rollouts"
+}
+```
+
+Create `backend/internal/models/workspace_file_audit.go`:
+
+```go
+package models
+
+import "time"
+
+type WorkspaceFileAudit struct {
+ ID int64 `db:"id,primarykey,autoincrement" json:"id"`
+ InstanceID int `db:"instance_id" json:"instance_id"`
+ UserID int `db:"user_id" json:"user_id"`
+ Action string `db:"action" json:"action"`
+ RelativePath string `db:"relative_path" json:"relative_path"`
+ Bytes int64 `db:"bytes" json:"bytes"`
+ CreatedAt time.Time `db:"created_at" json:"created_at"`
+}
+
+func (WorkspaceFileAudit) TableName() string {
+ return "workspace_file_audits"
+}
+```
+
+- [ ] **Step 6: Add repository interfaces and implementations**
+
+Implement interfaces with these method signatures. Use `upper/db` collections for normal CRUD and raw SQL for capacity claims requiring atomic increments.
+
+`backend/internal/repository/runtime_pod_repository.go`:
+
+```go
+package repository
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "clawreef/internal/models"
+ "github.com/upper/db/v4"
+)
+
+type RuntimePodRepository interface {
+ UpsertFromAgent(ctx context.Context, pod *models.RuntimePod) error
+ GetByID(ctx context.Context, id int64) (*models.RuntimePod, error)
+ GetByNamespaceName(ctx context.Context, namespace, podName string) (*models.RuntimePod, error)
+ List(ctx context.Context, runtimeType string) ([]models.RuntimePod, error)
+ ListSchedulable(ctx context.Context, runtimeType string) ([]models.RuntimePod, error)
+ TryClaimSlot(ctx context.Context, podID int64) (bool, error)
+ ReleaseSlot(ctx context.Context, podID int64) error
+ MarkState(ctx context.Context, podID int64, state string, draining bool) error
+ MarkUnseenUnhealthy(ctx context.Context, cutoff time.Time) error
+ UpdateMetrics(ctx context.Context, podID int64, metrics RuntimePodMetricsUpdate) error
+}
+
+type RuntimePodMetricsUpdate struct {
+ CPUMillisUsed int64
+ MemoryBytesUsed int64
+ DiskBytesUsed int64
+ NetworkRXBytes int64
+ NetworkTXBytes int64
+ MetricsJSON string
+ LastSeenAt time.Time
+}
+
+type runtimePodRepository struct {
+ sess db.Session
+}
+
+func NewRuntimePodRepository(sess db.Session) RuntimePodRepository {
+ return &runtimePodRepository{sess: sess}
+}
+
+func (r *runtimePodRepository) collection() db.Collection {
+ return r.sess.Collection("runtime_pods")
+}
+```
+
+Then add each method in the same file. The `TryClaimSlot` implementation must use this SQL shape:
+
+```go
+func (r *runtimePodRepository) TryClaimSlot(ctx context.Context, podID int64) (bool, error) {
+ res, err := r.sess.SQL().
+ ExecContext(ctx, `UPDATE runtime_pods
+ SET used_slots = used_slots + 1
+ WHERE id = ? AND state = 'ready' AND draining = 0 AND used_slots < capacity`, podID)
+ if err != nil {
+ return false, err
+ }
+ affected, err := res.RowsAffected()
+ if err != nil {
+ return false, err
+ }
+ return affected == 1, nil
+}
+```
+
+`backend/internal/repository/instance_runtime_binding_repository.go` must include:
+
+```go
+type InstanceRuntimeBindingRepository interface {
+ Create(ctx context.Context, binding *models.InstanceRuntimeBinding) error
+ GetByInstanceID(ctx context.Context, instanceID int) (*models.InstanceRuntimeBinding, error)
+ GetRunningByInstanceID(ctx context.Context, instanceID int) (*models.InstanceRuntimeBinding, error)
+ ListByRuntimePodID(ctx context.Context, runtimePodID int64) ([]models.InstanceRuntimeBinding, error)
+ ListByRuntimePodIDs(ctx context.Context, runtimePodIDs []int64) ([]models.InstanceRuntimeBinding, error)
+ UpdateRunning(ctx context.Context, instanceID int, generation int, gatewayID string, port int, pid *int) error
+ UpdateState(ctx context.Context, instanceID int, generation int, state string, message *string) error
+ DeleteByInstanceID(ctx context.Context, instanceID int) error
+}
+```
+
+Extend `backend/internal/repository/instance_repository.go` with:
+
+```go
+ GetV2DesiredRunning(ctx context.Context, limit int) ([]models.Instance, error)
+ GetV2Creating(ctx context.Context, limit int) ([]models.Instance, error)
+ UpdateRuntimeState(ctx context.Context, id int, status string, generation int, message *string) error
+ SetWorkspacePath(ctx context.Context, id int, workspacePath string) error
+ UpdateWorkspaceUsage(ctx context.Context, id int, usageBytes int64) error
+```
+
+- [ ] **Step 7: Run backend tests for schema compilation**
+
+Run:
+
+```powershell
+go test ./backend/internal/db ./backend/internal/models ./backend/internal/repository -count=1
+```
+
+Expected: pass, or report packages with no test files and no compile errors.
+
+- [ ] **Step 8: Commit schema and repository layer**
+
+Run:
+
+```powershell
+git add backend/internal/db backend/internal/models backend/internal/repository
+git commit -m "feat: add runtime pool schema"
+```
+
+## Task 2: Agent Contract Documentation And HTTP Client
+
+**Files:**
+- Create: `docs/clawmanager-agent-v2-contract.md`
+- Create: `backend/internal/services/runtime_agent_client.go`
+- Create: `backend/internal/services/runtime_agent_client_test.go`
+
+- [ ] **Step 1: Write the agent contract document**
+
+Create `docs/clawmanager-agent-v2-contract.md` with these sections:
+
+```markdown
+# clawmanager-agent V2 Contract
+
+## Purpose
+
+The agent runs inside each shared OpenClaw or Hermes runtime Pod. It manages gateway subprocesses, ports, cgroups, Linux users, workspace quota, health checks, skill/status reporting, and metrics.
+
+## Agent-To-Backend Reports
+
+All report requests use header `X-ClawManager-Agent-Token`.
+
+### POST /api/v1/runtime-agent/register
+
+Request body:
+
+```json
+{
+ "runtime_type": "openclaw",
+ "namespace": "clawmanager-system",
+ "pod_name": "openclaw-runtime-6f77f8b8c7-abcde",
+ "pod_uid": "pod-uid",
+ "pod_ip": "10.42.0.31",
+ "node_name": "node-a",
+ "deployment_name": "openclaw-runtime",
+ "image_ref": "ghcr.io/yuan-lab-llm/clawmanager-openclaw-image/openclaw:latest",
+ "agent_endpoint": "http://10.42.0.31:19090",
+ "capacity": 100
+}
+```
+
+### POST /api/v1/runtime-agent/heartbeat
+
+Request body:
+
+```json
+{
+ "pod_name": "openclaw-runtime-6f77f8b8c7-abcde",
+ "runtime_type": "openclaw",
+ "state": "ready",
+ "used_slots": 37,
+ "draining": false
+}
+```
+
+### POST /api/v1/runtime-agent/metrics/report
+
+Request body:
+
+```json
+{
+ "pod_name": "openclaw-runtime-6f77f8b8c7-abcde",
+ "cpu_millis_used": 13600,
+ "memory_bytes_used": 42949672960,
+ "disk_bytes_used": 214748364800,
+ "network_rx_bytes": 9223372,
+ "network_tx_bytes": 19223372,
+ "gateways": [
+ {
+ "instance_id": 123,
+ "gateway_id": "gw-123-7",
+ "port": 20017,
+ "state": "running",
+ "last_health_at": "2026-06-01T10:00:00Z"
+ }
+ ]
+}
+```
+
+## Backend-To-Agent Commands
+
+All command requests use header `X-ClawManager-Control-Token`.
+
+### POST /v1/gateways
+
+The agent creates a gateway subprocess and returns the bound port. If no port is free in the requested range, return HTTP 409.
+
+### DELETE /v1/gateways/{gateway_id}
+
+The agent stops the gateway and releases cgroup, process, and port resources.
+
+### POST /v1/drain
+
+The agent marks the Pod as draining and rejects new gateway creation. Existing gateways continue until ClawManager migrates them.
+
+## Isolation Requirements
+
+Every gateway runs as UID/GID `200000 + instance_id`. The agent rejects workspace paths outside `/workspaces/{runtime}/user-{user_id}/instance-{instance_id}` after resolving symlinks. CPU and memory limits are enforced with cgroups. Workspace quota is enforced before writes.
+```
+
+- [ ] **Step 2: Write failing client tests**
+
+Create `backend/internal/services/runtime_agent_client_test.go`:
+
+```go
+package services
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+)
+
+func TestRuntimeAgentClientCreateGateway(t *testing.T) {
+ var gotToken string
+ var gotReq RuntimeAgentCreateGatewayRequest
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/v1/gateways" {
+ t.Fatalf("unexpected path %s", r.URL.Path)
+ }
+ gotToken = r.Header.Get("X-ClawManager-Control-Token")
+ if err := json.NewDecoder(r.Body).Decode(&gotReq); err != nil {
+ t.Fatalf("decode request: %v", err)
+ }
+ _ = json.NewEncoder(w).Encode(RuntimeAgentCreateGatewayResponse{
+ GatewayID: "gw-7-3",
+ Port: 20017,
+ PID: intPtr(8842),
+ Status: "running",
+ })
+ }))
+ defer server.Close()
+
+ client := NewRuntimeAgentClient("secret")
+ resp, err := client.CreateGateway(context.Background(), server.URL, RuntimeAgentCreateGatewayRequest{
+ InstanceID: 7,
+ UserID: 8,
+ AgentType: "openclaw",
+ WorkspacePath: "/workspaces/openclaw/user-8/instance-7",
+ PortRange: RuntimeAgentPortRange{Start: 20000, End: 20099},
+ UID: 200007,
+ GID: 200007,
+ CPUCores: 2,
+ MemoryMB: 4096,
+ DiskQuotaMB: 20480,
+ Generation: 3,
+ })
+ if err != nil {
+ t.Fatalf("CreateGateway returned error: %v", err)
+ }
+ if gotToken != "secret" {
+ t.Fatalf("unexpected token %q", gotToken)
+ }
+ if gotReq.InstanceID != 7 || gotReq.PortRange.Start != 20000 {
+ t.Fatalf("unexpected request %#v", gotReq)
+ }
+ if resp.GatewayID != "gw-7-3" || resp.Port != 20017 {
+ t.Fatalf("unexpected response %#v", resp)
+ }
+}
+
+func TestRuntimeAgentClientConflict(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ http.Error(w, "no free port", http.StatusConflict)
+ }))
+ defer server.Close()
+
+ client := NewRuntimeAgentClient("secret")
+ _, err := client.CreateGateway(context.Background(), server.URL, RuntimeAgentCreateGatewayRequest{})
+ if err == nil || err.Error() != "runtime agent conflict: no free port\n" {
+ t.Fatalf("unexpected error %v", err)
+ }
+}
+
+func intPtr(v int) *int {
+ return &v
+}
+```
+
+- [ ] **Step 3: Run client tests and verify they fail**
+
+Run:
+
+```powershell
+go test ./backend/internal/services -run RuntimeAgentClient -count=1
+```
+
+Expected: fail because `RuntimeAgentCreateGatewayRequest` and `NewRuntimeAgentClient` do not exist.
+
+- [ ] **Step 4: Implement runtime agent client**
+
+Create `backend/internal/services/runtime_agent_client.go`:
+
+```go
+package services
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+ "time"
+)
+
+type RuntimeAgentClient interface {
+ Health(ctx context.Context, endpoint string) error
+ CreateGateway(ctx context.Context, endpoint string, req RuntimeAgentCreateGatewayRequest) (*RuntimeAgentCreateGatewayResponse, error)
+ DeleteGateway(ctx context.Context, endpoint, gatewayID string) error
+ Drain(ctx context.Context, endpoint string) error
+}
+
+type RuntimeAgentPortRange struct {
+ Start int `json:"start"`
+ End int `json:"end"`
+}
+
+type RuntimeAgentCreateGatewayRequest struct {
+ InstanceID int `json:"instance_id"`
+ UserID int `json:"user_id"`
+ AgentType string `json:"agent_type"`
+ WorkspacePath string `json:"workspace_path"`
+ PortRange RuntimeAgentPortRange `json:"port_range"`
+ UID int `json:"uid"`
+ GID int `json:"gid"`
+ CPUCores float64 `json:"cpu_cores"`
+ MemoryMB int `json:"memory_mb"`
+ DiskQuotaMB int `json:"disk_quota_mb"`
+ Generation int `json:"generation"`
+}
+
+type RuntimeAgentCreateGatewayResponse struct {
+ GatewayID string `json:"gateway_id"`
+ Port int `json:"port"`
+ PID *int `json:"pid,omitempty"`
+ Status string `json:"status"`
+}
+
+type runtimeAgentHTTPClient struct {
+ controlToken string
+ httpClient *http.Client
+}
+
+func NewRuntimeAgentClient(controlToken string) RuntimeAgentClient {
+ return &runtimeAgentHTTPClient{
+ controlToken: controlToken,
+ httpClient: &http.Client{
+ Timeout: 5 * time.Second,
+ },
+ }
+}
+
+func (c *runtimeAgentHTTPClient) Health(ctx context.Context, endpoint string) error {
+ return c.do(ctx, http.MethodGet, endpoint, "/v1/health", nil, nil)
+}
+
+func (c *runtimeAgentHTTPClient) CreateGateway(ctx context.Context, endpoint string, req RuntimeAgentCreateGatewayRequest) (*RuntimeAgentCreateGatewayResponse, error) {
+ var resp RuntimeAgentCreateGatewayResponse
+ if err := c.do(ctx, http.MethodPost, endpoint, "/v1/gateways", req, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
+
+func (c *runtimeAgentHTTPClient) DeleteGateway(ctx context.Context, endpoint, gatewayID string) error {
+ return c.do(ctx, http.MethodDelete, endpoint, "/v1/gateways/"+gatewayID, nil, nil)
+}
+
+func (c *runtimeAgentHTTPClient) Drain(ctx context.Context, endpoint string) error {
+ return c.do(ctx, http.MethodPost, endpoint, "/v1/drain", map[string]bool{"draining": true}, nil)
+}
+
+func (c *runtimeAgentHTTPClient) do(ctx context.Context, method, endpoint, path string, body any, out any) error {
+ endpoint = strings.TrimRight(endpoint, "/")
+ var reader io.Reader
+ if body != nil {
+ payload, err := json.Marshal(body)
+ if err != nil {
+ return err
+ }
+ reader = bytes.NewReader(payload)
+ }
+ req, err := http.NewRequestWithContext(ctx, method, endpoint+path, reader)
+ if err != nil {
+ return err
+ }
+ req.Header.Set("X-ClawManager-Control-Token", c.controlToken)
+ if body != nil {
+ req.Header.Set("Content-Type", "application/json")
+ }
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return err
+ }
+ defer resp.Body.Close()
+ if resp.StatusCode >= 400 {
+ msg, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+ if resp.StatusCode == http.StatusConflict {
+ return fmt.Errorf("runtime agent conflict: %s", string(msg))
+ }
+ return fmt.Errorf("runtime agent status %d: %s", resp.StatusCode, string(msg))
+ }
+ if out == nil {
+ return nil
+ }
+ return json.NewDecoder(resp.Body).Decode(out)
+}
+```
+
+- [ ] **Step 5: Run client tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/services -run RuntimeAgentClient -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 6: Commit agent contract and client**
+
+Run:
+
+```powershell
+git add docs/clawmanager-agent-v2-contract.md backend/internal/services/runtime_agent_client.go backend/internal/services/runtime_agent_client_test.go
+git commit -m "feat: add runtime agent contract"
+```
+
+## Task 3: Runtime Capacity, Kubernetes Runtime Deployments, And Leader Election
+
+**Files:**
+- Create: `backend/internal/services/runtime_capacity.go`
+- Create: `backend/internal/services/runtime_capacity_test.go`
+- Create: `backend/internal/services/runtime_leader.go`
+- Create: `backend/internal/services/k8s/runtime_deployment_service.go`
+- Create: `backend/internal/services/k8s/runtime_deployment_service_test.go`
+- Modify: `backend/internal/config/config.go`
+
+- [ ] **Step 1: Write runtime capacity tests**
+
+Create `backend/internal/services/runtime_capacity_test.go`:
+
+```go
+package services
+
+import "testing"
+
+func TestNormalizeV2RuntimeType(t *testing.T) {
+ tests := map[string]string{
+ "openclaw": "openclaw",
+ "hermes": "hermes",
+ "webtop": "",
+ "ubuntu": "",
+ }
+ for input, want := range tests {
+ got, ok := NormalizeV2RuntimeType(input)
+ if want == "" {
+ if ok {
+ t.Fatalf("expected %s to be rejected", input)
+ }
+ continue
+ }
+ if !ok || got != want {
+ t.Fatalf("NormalizeV2RuntimeType(%q) = %q, %v", input, got, ok)
+ }
+ }
+}
+
+func TestRuntimeWorkspacePath(t *testing.T) {
+ got := RuntimeWorkspacePath("openclaw", 45, 123)
+ want := "/workspaces/openclaw/user-45/instance-123"
+ if got != want {
+ t.Fatalf("workspace path mismatch: want %s got %s", want, got)
+ }
+}
+
+func TestRuntimeLinuxID(t *testing.T) {
+ got := RuntimeLinuxID(123)
+ if got != 200123 {
+ t.Fatalf("runtime linux id mismatch: %d", got)
+ }
+}
+```
+
+- [ ] **Step 2: Implement capacity helpers**
+
+Create `backend/internal/services/runtime_capacity.go`:
+
+```go
+package services
+
+import "fmt"
+
+const (
+ RuntimeTypeOpenClaw = "openclaw"
+ RuntimeTypeHermes = "hermes"
+
+ RuntimeGatewayPortStart = 20000
+ RuntimeGatewayPortEnd = 20099
+ RuntimePodCapacity = 100
+ RuntimeLinuxIDBase = 200000
+)
+
+func NormalizeV2RuntimeType(instanceType string) (string, bool) {
+ switch instanceType {
+ case RuntimeTypeOpenClaw:
+ return RuntimeTypeOpenClaw, true
+ case RuntimeTypeHermes:
+ return RuntimeTypeHermes, true
+ default:
+ return "", false
+ }
+}
+
+func RuntimeWorkspacePath(runtimeType string, userID int, instanceID int) string {
+ return fmt.Sprintf("/workspaces/%s/user-%d/instance-%d", runtimeType, userID, instanceID)
+}
+
+func RuntimeLinuxID(instanceID int) int {
+ return RuntimeLinuxIDBase + instanceID
+}
+```
+
+- [ ] **Step 3: Run capacity tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/services -run 'NormalizeV2RuntimeType|RuntimeWorkspacePath|RuntimeLinuxID' -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 4: Add runtime config fields**
+
+Modify `backend/internal/config/config.go` by adding fields to the main config struct:
+
+```go
+ Runtime RuntimeConfig
+```
+
+Add this struct and env parsing:
+
+```go
+type RuntimeConfig struct {
+ Namespace string
+ WorkspaceRoot string
+ AgentControlToken string
+ AgentReportToken string
+ BackendReplicaID string
+ RedisURL string
+ SchedulerEnabled bool
+ HeartbeatTimeout time.Duration
+ SchedulerTick time.Duration
+ OpenClawImage string
+ HermesImage string
+ MaxGatewaysPerPod int
+ GatewayPortStart int
+ GatewayPortEnd int
+}
+```
+
+Parse with defaults:
+
+```go
+Runtime: RuntimeConfig{
+ Namespace: getEnv("RUNTIME_NAMESPACE", getEnv("K8S_NAMESPACE", "clawmanager-system")),
+ WorkspaceRoot: getEnv("RUNTIME_WORKSPACE_ROOT", "/workspaces"),
+ AgentControlToken: getEnv("RUNTIME_AGENT_CONTROL_TOKEN", ""),
+ AgentReportToken: getEnv("RUNTIME_AGENT_REPORT_TOKEN", ""),
+ BackendReplicaID: getEnv("HOSTNAME", "clawmanager-backend-local"),
+ RedisURL: getEnv("PLATFORM_REDIS_URL", getEnv("TEAM_REDIS_URL", "")),
+ SchedulerEnabled: getEnvBool("RUNTIME_SCHEDULER_ENABLED", true),
+ HeartbeatTimeout: getEnvDuration("RUNTIME_HEARTBEAT_TIMEOUT", 10*time.Second),
+ SchedulerTick: getEnvDuration("RUNTIME_SCHEDULER_TICK", 2*time.Second),
+ OpenClawImage: getEnv("OPENCLAW_RUNTIME_IMAGE", "ghcr.io/yuan-lab-llm/clawmanager-openclaw-image/openclaw:latest"),
+ HermesImage: getEnv("HERMES_RUNTIME_IMAGE", "ghcr.io/yuan-lab-llm/clawmanager-openclaw-image/openclaw:latest"),
+ MaxGatewaysPerPod: getEnvInt("RUNTIME_MAX_GATEWAYS_PER_POD", RuntimePodCapacity),
+ GatewayPortStart: getEnvInt("RUNTIME_GATEWAY_PORT_START", RuntimeGatewayPortStart),
+ GatewayPortEnd: getEnvInt("RUNTIME_GATEWAY_PORT_END", RuntimeGatewayPortEnd),
+},
+```
+
+If `getEnvDuration`, `getEnvBool`, or `getEnvInt` is missing, add them in `config.go` using `strconv` and `time.ParseDuration`.
+
+- [ ] **Step 5: Add Kubernetes runtime deployment service test**
+
+Create `backend/internal/services/k8s/runtime_deployment_service_test.go` with a unit test that constructs the Deployment and checks the shared workspace mount:
+
+```go
+package k8s
+
+import "testing"
+
+func TestBuildRuntimeDeploymentUsesSharedWorkspaceAndAgentPort(t *testing.T) {
+ dep := BuildRuntimeDeployment(RuntimeDeploymentSpec{
+ Name: "openclaw-runtime",
+ Namespace: "clawmanager-system",
+ RuntimeType: "openclaw",
+ Image: "example/openclaw:latest",
+ Replicas: 2,
+ WorkspaceNFSServer: "workspace-store.clawmanager-system.svc.cluster.local",
+ WorkspaceNFSPath: "/exports/workspaces",
+ AgentControlToken: "control",
+ AgentReportToken: "report",
+ })
+
+ if dep.Name != "openclaw-runtime" || *dep.Spec.Replicas != 2 {
+ t.Fatalf("unexpected deployment identity %#v", dep)
+ }
+ container := dep.Spec.Template.Spec.Containers[0]
+ if container.Ports[0].ContainerPort != 19090 {
+ t.Fatalf("agent port missing: %#v", container.Ports)
+ }
+ foundWorkspace := false
+ for _, mount := range container.VolumeMounts {
+ if mount.Name == "workspaces" && mount.MountPath == "/workspaces" {
+ foundWorkspace = true
+ }
+ }
+ if !foundWorkspace {
+ t.Fatalf("workspace mount missing: %#v", container.VolumeMounts)
+ }
+}
+```
+
+- [ ] **Step 6: Implement Kubernetes runtime deployment service**
+
+Create `backend/internal/services/k8s/runtime_deployment_service.go` with:
+
+```go
+package k8s
+
+import (
+ "context"
+
+ appsv1 "k8s.io/api/apps/v1"
+ corev1 "k8s.io/api/core/v1"
+ metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+ "k8s.io/apimachinery/pkg/api/resource"
+ "k8s.io/client-go/kubernetes"
+)
+
+type RuntimeDeploymentSpec struct {
+ Name string
+ Namespace string
+ RuntimeType string
+ Image string
+ Replicas int32
+ WorkspaceNFSServer string
+ WorkspaceNFSPath string
+ AgentControlToken string
+ AgentReportToken string
+}
+
+type RuntimeDeploymentService interface {
+ Ensure(ctx context.Context, spec RuntimeDeploymentSpec) error
+ Scale(ctx context.Context, namespace, name string, replicas int32) error
+}
+
+type runtimeDeploymentService struct {
+ client kubernetes.Interface
+}
+
+func NewRuntimeDeploymentService(client kubernetes.Interface) RuntimeDeploymentService {
+ return &runtimeDeploymentService{client: client}
+}
+
+func int32Ptr(v int32) *int32 {
+ return &v
+}
+
+func BuildRuntimeDeployment(spec RuntimeDeploymentSpec) *appsv1.Deployment {
+ labels := map[string]string{
+ "app": spec.Name,
+ "clawmanager.io/runtime-type": spec.RuntimeType,
+ }
+ return &appsv1.Deployment{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: spec.Name,
+ Namespace: spec.Namespace,
+ Labels: labels,
+ },
+ Spec: appsv1.DeploymentSpec{
+ Replicas: int32Ptr(spec.Replicas),
+ Selector: &metav1.LabelSelector{MatchLabels: labels},
+ Template: corev1.PodTemplateSpec{
+ ObjectMeta: metav1.ObjectMeta{Labels: labels},
+ Spec: corev1.PodSpec{
+ Containers: []corev1.Container{{
+ Name: "runtime",
+ Image: spec.Image,
+ Ports: []corev1.ContainerPort{{
+ Name: "agent",
+ ContainerPort: 19090,
+ }},
+ Env: []corev1.EnvVar{
+ {Name: "CLAWMANAGER_RUNTIME_TYPE", Value: spec.RuntimeType},
+ {Name: "CLAWMANAGER_AGENT_PORT", Value: "19090"},
+ {Name: "CLAWMANAGER_GATEWAY_PORT_START", Value: "20000"},
+ {Name: "CLAWMANAGER_GATEWAY_PORT_END", Value: "20099"},
+ {Name: "CLAWMANAGER_AGENT_CONTROL_TOKEN", Value: spec.AgentControlToken},
+ {Name: "CLAWMANAGER_AGENT_REPORT_TOKEN", Value: spec.AgentReportToken},
+ },
+ Resources: corev1.ResourceRequirements{
+ Requests: corev1.ResourceList{
+ corev1.ResourceCPU: resource.MustParse("500m"),
+ corev1.ResourceMemory: resource.MustParse("1Gi"),
+ },
+ },
+ VolumeMounts: []corev1.VolumeMount{{
+ Name: "workspaces",
+ MountPath: "/workspaces",
+ }},
+ }},
+ Volumes: []corev1.Volume{{
+ Name: "workspaces",
+ VolumeSource: corev1.VolumeSource{
+ NFS: &corev1.NFSVolumeSource{
+ Server: spec.WorkspaceNFSServer,
+ Path: spec.WorkspaceNFSPath,
+ },
+ },
+ }},
+ },
+ },
+ },
+ }
+}
+```
+
+Add `Ensure` and `Scale` using AppsV1 Deployments `Get`, `Create`, `Update`, and `UpdateScale`.
+
+- [ ] **Step 7: Implement Lease leader service**
+
+Create `backend/internal/services/runtime_leader.go`:
+
+```go
+package services
+
+import (
+ "context"
+ "time"
+
+ coordinationv1 "k8s.io/api/coordination/v1"
+ metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+ "k8s.io/client-go/kubernetes"
+)
+
+type RuntimeLeaderService interface {
+ IsLeader(ctx context.Context) bool
+}
+
+type runtimeLeaderService struct {
+ client kubernetes.Interface
+ namespace string
+ name string
+ holder string
+ ttl time.Duration
+}
+
+func NewRuntimeLeaderService(client kubernetes.Interface, namespace, holder string) RuntimeLeaderService {
+ return &runtimeLeaderService{
+ client: client,
+ namespace: namespace,
+ name: "clawmanager-runtime-scheduler",
+ holder: holder,
+ ttl: 15 * time.Second,
+ }
+}
+
+func (s *runtimeLeaderService) IsLeader(ctx context.Context) bool {
+ now := metav1.Now()
+ leaseClient := s.client.CoordinationV1().Leases(s.namespace)
+ lease, err := leaseClient.Get(ctx, s.name, metav1.GetOptions{})
+ if err != nil {
+ lease = &coordinationv1.Lease{
+ ObjectMeta: metav1.ObjectMeta{Name: s.name, Namespace: s.namespace},
+ Spec: coordinationv1.LeaseSpec{
+ HolderIdentity: &s.holder,
+ RenewTime: &now,
+ LeaseDurationSeconds: int32Ptr32(int32(s.ttl.Seconds())),
+ },
+ }
+ _, createErr := leaseClient.Create(ctx, lease, metav1.CreateOptions{})
+ return createErr == nil
+ }
+ if lease.Spec.HolderIdentity != nil && *lease.Spec.HolderIdentity != s.holder && lease.Spec.RenewTime != nil {
+ expires := lease.Spec.RenewTime.Time.Add(s.ttl)
+ if time.Now().Before(expires) {
+ return false
+ }
+ }
+ lease.Spec.HolderIdentity = &s.holder
+ lease.Spec.RenewTime = &now
+ _, err = leaseClient.Update(ctx, lease, metav1.UpdateOptions{})
+ return err == nil
+}
+
+func int32Ptr32(v int32) *int32 {
+ return &v
+}
+```
+
+- [ ] **Step 8: Run runtime deployment and leader tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/services ./backend/internal/services/k8s -run 'Runtime|Leader' -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 9: Commit runtime capacity and Kubernetes services**
+
+Run:
+
+```powershell
+git add backend/internal/config backend/internal/services backend/internal/services/k8s
+git commit -m "feat: add runtime pool infrastructure services"
+```
+
+## Task 4: Runtime Scheduler And Redis Event Fanout
+
+**Files:**
+- Create: `backend/internal/services/redis_client.go`
+- Create: `backend/internal/services/runtime_events.go`
+- Create: `backend/internal/services/runtime_scheduler.go`
+- Create: `backend/internal/services/runtime_scheduler_test.go`
+- Modify: `backend/cmd/server/main.go`
+
+- [ ] **Step 1: Extract a platform Redis client**
+
+Create `backend/internal/services/redis_client.go` by reusing the existing RESP parsing pattern from `team_redis.go`. The exported interface must be:
+
+```go
+type PlatformRedisClient interface {
+ SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error)
+ Del(ctx context.Context, key string) error
+ XAdd(ctx context.Context, key string, fields map[string]string) (string, error)
+ XRead(ctx context.Context, key, lastID string, block time.Duration) ([]redisStreamMessage, error)
+}
+```
+
+Use the same URL parsing behavior as `newRedisBus`, and add:
+
+```go
+func NewPlatformRedisClient(rawURL string) (PlatformRedisClient, error) {
+ return newRedisBus(rawURL)
+}
+```
+
+Extend `redisBus` in `team_redis.go` only if needed so the same type satisfies `SetNX` and `Del`:
+
+```go
+func (b *redisBus) SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error) {
+ reply, err := b.do(ctx, "SET", key, value, "NX", "PX", fmt.Sprintf("%d", ttl.Milliseconds()))
+ if err != nil {
+ return false, err
+ }
+ return reply == "OK", nil
+}
+
+func (b *redisBus) Del(ctx context.Context, key string) error {
+ _, err := b.do(ctx, "DEL", key)
+ return err
+}
+```
+
+- [ ] **Step 2: Add runtime event service**
+
+Create `backend/internal/services/runtime_events.go`:
+
+```go
+package services
+
+import (
+ "context"
+ "encoding/json"
+ "time"
+)
+
+const runtimeEventStreamKey = "clawmanager:runtime-events"
+
+type RuntimeEvent struct {
+ Type string `json:"type"`
+ Payload json.RawMessage `json:"payload"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+type RuntimeEventService interface {
+ Publish(ctx context.Context, eventType string, payload any) error
+ Read(ctx context.Context, lastID string, block time.Duration) ([]redisStreamMessage, error)
+}
+
+type runtimeEventService struct {
+ redis PlatformRedisClient
+}
+
+func NewRuntimeEventService(redis PlatformRedisClient) RuntimeEventService {
+ return &runtimeEventService{redis: redis}
+}
+
+func (s *runtimeEventService) Publish(ctx context.Context, eventType string, payload any) error {
+ raw, err := json.Marshal(payload)
+ if err != nil {
+ return err
+ }
+ event := RuntimeEvent{Type: eventType, Payload: raw, CreatedAt: time.Now().UTC()}
+ eventRaw, err := json.Marshal(event)
+ if err != nil {
+ return err
+ }
+ _, err = s.redis.XAdd(ctx, runtimeEventStreamKey, map[string]string{"event": string(eventRaw)})
+ return err
+}
+
+func (s *runtimeEventService) Read(ctx context.Context, lastID string, block time.Duration) ([]redisStreamMessage, error) {
+ return s.redis.XRead(ctx, runtimeEventStreamKey, lastID, block)
+}
+```
+
+- [ ] **Step 3: Write scheduler assignment test with fakes**
+
+Create `backend/internal/services/runtime_scheduler_test.go` with fake repositories and this test:
+
+```go
+func TestRuntimeSchedulerAssignsCreatingInstanceToReadyPod(t *testing.T) {
+ instance := models.Instance{ID: 123, UserID: 45, Type: "openclaw", CPUCores: 2, MemoryGB: 4, DiskGB: 20, RuntimeGeneration: 1}
+ pod := models.RuntimePod{ID: 9, RuntimeType: "openclaw", PodIP: stringPtr("10.42.0.31"), AgentEndpoint: stringPtr("http://10.42.0.31:19090"), State: "ready", Capacity: 100, UsedSlots: 0}
+ s := newRuntimeSchedulerForTest(instance, pod)
+
+ if err := s.assignInstance(context.Background(), instance); err != nil {
+ t.Fatalf("assignInstance returned error: %v", err)
+ }
+ if s.fakeAgent.createGatewayCalls != 1 {
+ t.Fatalf("expected one create gateway call, got %d", s.fakeAgent.createGatewayCalls)
+ }
+ binding := s.fakeBindings.byInstance[123]
+ if binding.GatewayPort != 20017 || binding.RuntimePodID != 9 {
+ t.Fatalf("unexpected binding %#v", binding)
+ }
+}
+```
+
+The fake agent must return:
+
+```go
+&RuntimeAgentCreateGatewayResponse{
+ GatewayID: "gw-123-1",
+ Port: 20017,
+ PID: intPtr(8842),
+ Status: "running",
+}
+```
+
+- [ ] **Step 4: Implement scheduler**
+
+Create `backend/internal/services/runtime_scheduler.go` with:
+
+```go
+package services
+
+import (
+ "context"
+ "fmt"
+ "log"
+ "time"
+
+ "clawreef/internal/models"
+ "clawreef/internal/repository"
+ k8ssvc "clawreef/internal/services/k8s"
+)
+
+type RuntimeScheduler struct {
+ instanceRepo repository.InstanceRepository
+ podRepo repository.RuntimePodRepository
+ bindingRepo repository.InstanceRuntimeBindingRepository
+ rolloutRepo repository.RuntimeRolloutRepository
+ agentClient RuntimeAgentClient
+ events RuntimeEventService
+ leader RuntimeLeaderService
+ deployments k8ssvc.RuntimeDeploymentService
+ tick time.Duration
+}
+
+func NewRuntimeScheduler(
+ instanceRepo repository.InstanceRepository,
+ podRepo repository.RuntimePodRepository,
+ bindingRepo repository.InstanceRuntimeBindingRepository,
+ rolloutRepo repository.RuntimeRolloutRepository,
+ agentClient RuntimeAgentClient,
+ events RuntimeEventService,
+ leader RuntimeLeaderService,
+ deployments k8ssvc.RuntimeDeploymentService,
+ tick time.Duration,
+) *RuntimeScheduler {
+ return &RuntimeScheduler{
+ instanceRepo: instanceRepo,
+ podRepo: podRepo,
+ bindingRepo: bindingRepo,
+ rolloutRepo: rolloutRepo,
+ agentClient: agentClient,
+ events: events,
+ leader: leader,
+ deployments: deployments,
+ tick: tick,
+ }
+}
+
+func (s *RuntimeScheduler) Start(ctx context.Context) {
+ go func() {
+ ticker := time.NewTicker(s.tick)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-ticker.C:
+ if !s.leader.IsLeader(ctx) {
+ continue
+ }
+ if err := s.reconcile(ctx); err != nil {
+ log.Printf("runtime scheduler reconcile failed: %v", err)
+ }
+ }
+ }
+ }()
+}
+
+func (s *RuntimeScheduler) reconcile(ctx context.Context) error {
+ creating, err := s.instanceRepo.GetV2Creating(ctx, 100)
+ if err != nil {
+ return err
+ }
+ for _, instance := range creating {
+ if err := s.assignInstance(ctx, instance); err != nil {
+ msg := err.Error()
+ _ = s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "error", instance.RuntimeGeneration, &msg)
+ }
+ }
+ running, err := s.instanceRepo.GetV2DesiredRunning(ctx, 200)
+ if err != nil {
+ return err
+ }
+ for _, instance := range running {
+ if _, err := s.bindingRepo.GetRunningByInstanceID(ctx, instance.ID); err != nil {
+ if assignErr := s.assignInstance(ctx, instance); assignErr != nil {
+ msg := assignErr.Error()
+ _ = s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "error", instance.RuntimeGeneration, &msg)
+ }
+ }
+ }
+ return nil
+}
+
+func (s *RuntimeScheduler) assignInstance(ctx context.Context, instance models.Instance) error {
+ runtimeType, ok := NormalizeV2RuntimeType(instance.Type)
+ if !ok {
+ return fmt.Errorf("unsupported V2 runtime type %s", instance.Type)
+ }
+ pods, err := s.podRepo.ListSchedulable(ctx, runtimeType)
+ if err != nil {
+ return err
+ }
+ for _, pod := range pods {
+ if pod.AgentEndpoint == nil {
+ continue
+ }
+ claimed, err := s.podRepo.TryClaimSlot(ctx, pod.ID)
+ if err != nil {
+ return err
+ }
+ if !claimed {
+ continue
+ }
+ if err := s.createGatewayOnPod(ctx, instance, pod); err != nil {
+ _ = s.podRepo.ReleaseSlot(ctx, pod.ID)
+ continue
+ }
+ return nil
+ }
+ return fmt.Errorf("no schedulable runtime pod for %s", runtimeType)
+}
+
+func (s *RuntimeScheduler) createGatewayOnPod(ctx context.Context, instance models.Instance, pod models.RuntimePod) error {
+ workspacePath := RuntimeWorkspacePath(pod.RuntimeType, instance.UserID, instance.ID)
+ linuxID := RuntimeLinuxID(instance.ID)
+ resp, err := s.agentClient.CreateGateway(ctx, *pod.AgentEndpoint, RuntimeAgentCreateGatewayRequest{
+ InstanceID: instance.ID,
+ UserID: instance.UserID,
+ AgentType: pod.RuntimeType,
+ WorkspacePath: workspacePath,
+ PortRange: RuntimeAgentPortRange{Start: RuntimeGatewayPortStart, End: RuntimeGatewayPortEnd},
+ UID: linuxID,
+ GID: linuxID,
+ CPUCores: instance.CPUCores,
+ MemoryMB: instance.MemoryGB * 1024,
+ DiskQuotaMB: instance.DiskGB * 1024,
+ Generation: instance.RuntimeGeneration,
+ })
+ if err != nil {
+ return err
+ }
+ binding := &models.InstanceRuntimeBinding{
+ InstanceID: instance.ID,
+ RuntimePodID: pod.ID,
+ RuntimeType: pod.RuntimeType,
+ GatewayID: resp.GatewayID,
+ GatewayPort: resp.Port,
+ GatewayPID: resp.PID,
+ WorkspacePath: workspacePath,
+ State: "running",
+ Generation: instance.RuntimeGeneration,
+ }
+ if err := s.bindingRepo.Create(ctx, binding); err != nil {
+ return err
+ }
+ if err := s.instanceRepo.SetWorkspacePath(ctx, instance.ID, workspacePath); err != nil {
+ return err
+ }
+ return s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "running", instance.RuntimeGeneration, nil)
+}
+```
+
+Add failover and rollout in the same file with these public methods:
+
+```go
+func (s *RuntimeScheduler) DrainPod(ctx context.Context, podID int64) error
+func (s *RuntimeScheduler) FailoverPod(ctx context.Context, podID int64, reason string) error
+func (s *RuntimeScheduler) StartRollout(ctx context.Context, rolloutID int64) error
+```
+
+`FailoverPod` must mark the Pod `unhealthy`, list its bindings, delete each binding, release the old slot, increment instance generation, set instance status `creating`, and let the next scheduler tick recreate the gateway on another Pod.
+
+- [ ] **Step 5: Wire scheduler in `main.go`**
+
+In `backend/cmd/server/main.go`, create the new repositories after the existing repositories:
+
+```go
+runtimePodRepo := repository.NewRuntimePodRepository(sess)
+bindingRepo := repository.NewInstanceRuntimeBindingRepository(sess)
+rolloutRepo := repository.NewRuntimeRolloutRepository(sess)
+```
+
+Create Redis and runtime services:
+
+```go
+platformRedis, err := services.NewPlatformRedisClient(cfg.Runtime.RedisURL)
+if err != nil {
+ log.Printf("platform redis disabled: %v", err)
+}
+runtimeEvents := services.NewRuntimeEventService(platformRedis)
+agentClient := services.NewRuntimeAgentClient(cfg.Runtime.AgentControlToken)
+leader := services.NewRuntimeLeaderService(k8sClient, cfg.Runtime.Namespace, cfg.Runtime.BackendReplicaID)
+runtimeDeployments := k8s.NewRuntimeDeploymentService(k8sClient)
+runtimeScheduler := services.NewRuntimeScheduler(instanceRepo, runtimePodRepo, bindingRepo, rolloutRepo, agentClient, runtimeEvents, leader, runtimeDeployments, cfg.Runtime.SchedulerTick)
+if cfg.Runtime.SchedulerEnabled {
+ runtimeScheduler.Start(ctx)
+}
+```
+
+If `platformRedis` can be nil in local development, make `NewRuntimeEventService` accept nil and return a no-op service that never panics.
+
+- [ ] **Step 6: Run scheduler tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/services -run RuntimeScheduler -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 7: Commit scheduler**
+
+Run:
+
+```powershell
+git add backend/internal/services backend/cmd/server/main.go
+git commit -m "feat: add runtime scheduler"
+```
+
+## Task 5: V2 Instance Lifecycle And Pod-IP Proxy
+
+**Files:**
+- Modify: `backend/internal/services/instance_service.go`
+- Modify: `backend/internal/services/instance_proxy_service.go`
+- Modify: `backend/internal/services/sync_service.go`
+- Modify: `backend/internal/handlers/instance_handler.go`
+- Modify: `backend/cmd/server/main.go`
+- Create: `backend/internal/services/instance_proxy_service_v2_test.go`
+
+- [ ] **Step 1: Add proxy test for binding target**
+
+Create `backend/internal/services/instance_proxy_service_v2_test.go` with a test that builds an instance, a binding, and a runtime Pod:
+
+```go
+func TestInstanceProxyServiceUsesRuntimeBindingForV2(t *testing.T) {
+ target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/apps/openclaw" {
+ t.Fatalf("unexpected path %s", r.URL.Path)
+ }
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte("ok"))
+ }))
+ defer target.Close()
+
+ podIP, port := splitHostPortForTest(t, target.URL)
+ instance := models.Instance{ID: 123, UserID: 45, Type: "openclaw", Status: "running"}
+ binding := models.InstanceRuntimeBinding{InstanceID: 123, RuntimePodID: 9, GatewayPort: port, State: "running"}
+ pod := models.RuntimePod{ID: 9, PodIP: &podIP, State: "ready"}
+
+ service := newProxyServiceForV2Test(instance, binding, pod)
+ req := httptest.NewRequest(http.MethodGet, "/api/v1/instances/123/proxy/apps/openclaw", nil)
+ rec := httptest.NewRecorder()
+
+ service.Proxy(rec, req, 123, "/apps/openclaw")
+ if rec.Code != http.StatusOK || rec.Body.String() != "ok" {
+ t.Fatalf("unexpected proxy response %d %q", rec.Code, rec.Body.String())
+ }
+}
+```
+
+- [ ] **Step 2: Modify instance creation for V2**
+
+In `backend/internal/services/instance_service.go`, keep legacy behavior for non-V2 types and add this branch near the start of create:
+
+```go
+runtimeType, isV2 := NormalizeV2RuntimeType(req.Type)
+if isV2 {
+ instance := &models.Instance{
+ UserID: userID,
+ Name: strings.TrimSpace(req.Name),
+ Description: normalizeStringPtr(req.Description),
+ Type: runtimeType,
+ RuntimeType: "gateway",
+ Status: "creating",
+ CPUCores: req.CPUCores,
+ MemoryGB: req.MemoryGB,
+ DiskGB: req.DiskGB,
+ StorageClass: strings.TrimSpace(req.StorageClass),
+ MountPath: "/workspaces",
+ RuntimeGeneration: 1,
+ }
+ if err := s.instanceRepo.Create(ctx, instance); err != nil {
+ return nil, err
+ }
+ workspacePath := RuntimeWorkspacePath(runtimeType, userID, instance.ID)
+ if err := os.MkdirAll(workspacePath, 0750); err != nil {
+ return nil, err
+ }
+ if err := s.instanceRepo.SetWorkspacePath(ctx, instance.ID, workspacePath); err != nil {
+ return nil, err
+ }
+ instance.WorkspacePath = &workspacePath
+ return instance, nil
+}
+```
+
+Keep validation so new creation accepts only `openclaw` and `hermes`; old records with `ubuntu`, `webtop`, `debian`, `centos`, or `custom` remain readable and manageable through legacy paths.
+
+- [ ] **Step 3: Modify start, stop, restart, delete**
+
+For V2 instances in `instance_service.go`:
+
+```go
+func (s *instanceService) Start(ctx context.Context, userID int, instanceID int) error {
+ instance, err := s.mustOwnInstance(ctx, userID, instanceID)
+ if err != nil {
+ return err
+ }
+ if _, ok := NormalizeV2RuntimeType(instance.Type); ok {
+ return s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "creating", instance.RuntimeGeneration+1, nil)
+ }
+ return s.startLegacy(ctx, instance)
+}
+
+func (s *instanceService) Stop(ctx context.Context, userID int, instanceID int) error {
+ instance, err := s.mustOwnInstance(ctx, userID, instanceID)
+ if err != nil {
+ return err
+ }
+ if _, ok := NormalizeV2RuntimeType(instance.Type); ok {
+ binding, err := s.bindingRepo.GetByInstanceID(ctx, instance.ID)
+ if err == nil {
+ pod, podErr := s.runtimePodRepo.GetByID(ctx, binding.RuntimePodID)
+ if podErr == nil && pod.AgentEndpoint != nil {
+ _ = s.agentClient.DeleteGateway(ctx, *pod.AgentEndpoint, binding.GatewayID)
+ }
+ _ = s.bindingRepo.DeleteByInstanceID(ctx, instance.ID)
+ _ = s.runtimePodRepo.ReleaseSlot(ctx, binding.RuntimePodID)
+ }
+ return s.instanceRepo.UpdateRuntimeState(ctx, instance.ID, "stopped", instance.RuntimeGeneration, nil)
+ }
+ return s.stopLegacy(ctx, instance)
+}
+```
+
+Use the existing legacy code by moving old logic into private helpers `startLegacy`, `stopLegacy`, and `deleteLegacy`.
+
+- [ ] **Step 4: Modify status for ordinary users**
+
+In `backend/internal/handlers/instance_handler.go`, make `/instances/:id/status` return user-safe availability for V2:
+
+```json
+{
+ "instance_status": {
+ "instance_id": 123,
+ "status": "running",
+ "availability": "available",
+ "agent_type": "openclaw",
+ "workspace_usage_bytes": 123456
+ }
+}
+```
+
+Do not include Pod name, namespace, Pod IP, service name, port, capacity, node, or runtime scheduling fields for normal users.
+
+- [ ] **Step 5: Modify proxy for V2**
+
+In `backend/internal/services/instance_proxy_service.go`, resolve target for V2:
+
+```go
+func (s *instanceProxyService) resolveV2Target(ctx context.Context, instanceID int) (*url.URL, error) {
+ binding, err := s.bindingRepo.GetRunningByInstanceID(ctx, instanceID)
+ if err != nil {
+ return nil, fmt.Errorf("instance gateway is not available")
+ }
+ pod, err := s.runtimePodRepo.GetByID(ctx, binding.RuntimePodID)
+ if err != nil {
+ return nil, err
+ }
+ if pod.PodIP == nil || *pod.PodIP == "" {
+ return nil, fmt.Errorf("runtime pod ip is not available")
+ }
+ return &url.URL{Scheme: "http", Host: net.JoinHostPort(*pod.PodIP, strconv.Itoa(binding.GatewayPort))}, nil
+}
+```
+
+Use this target when `NormalizeV2RuntimeType(instance.Type)` succeeds, otherwise execute the existing Service-based proxy path.
+
+- [ ] **Step 6: Run lifecycle and proxy tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/services -run 'Instance|Proxy|RuntimeScheduler' -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 7: Commit lifecycle and proxy**
+
+Run:
+
+```powershell
+git add backend/internal/services backend/internal/handlers backend/cmd/server/main.go
+git commit -m "feat: route V2 instances through runtime gateways"
+```
+
+## Task 6: Workspace File Manager Backend
+
+**Files:**
+- Create: `backend/internal/services/workspace_path_guard.go`
+- Create: `backend/internal/services/workspace_path_guard_test.go`
+- Create: `backend/internal/services/workspace_file_service.go`
+- Create: `backend/internal/services/workspace_file_service_test.go`
+- Create: `backend/internal/handlers/workspace_file_handler.go`
+- Modify: `backend/internal/utils/response.go`
+- Modify: `backend/cmd/server/main.go`
+
+- [ ] **Step 1: Write path guard tests**
+
+Create `backend/internal/services/workspace_path_guard_test.go`:
+
+```go
+package services
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestResolveWorkspacePathRejectsTraversal(t *testing.T) {
+ root := t.TempDir()
+ _, err := ResolveWorkspacePath(root, "../outside.txt")
+ if err == nil || err.Error() != "workspace path escapes instance workspace" {
+ t.Fatalf("unexpected error %v", err)
+ }
+}
+
+func TestResolveWorkspacePathRejectsSymlinkEscape(t *testing.T) {
+ root := t.TempDir()
+ outside := t.TempDir()
+ if err := os.Symlink(outside, filepath.Join(root, "escape")); err != nil {
+ t.Skipf("symlink unavailable: %v", err)
+ }
+ _, err := ResolveWorkspacePath(root, "escape/file.txt")
+ if err == nil || err.Error() != "workspace path escapes instance workspace" {
+ t.Fatalf("unexpected error %v", err)
+ }
+}
+
+func TestResolveWorkspacePathAllowsNestedFile(t *testing.T) {
+ root := t.TempDir()
+ got, err := ResolveWorkspacePath(root, "a/b.txt")
+ if err != nil {
+ t.Fatalf("ResolveWorkspacePath returned error: %v", err)
+ }
+ want := filepath.Join(root, "a", "b.txt")
+ if got != want {
+ t.Fatalf("want %s got %s", want, got)
+ }
+}
+```
+
+- [ ] **Step 2: Implement path guard**
+
+Create `backend/internal/services/workspace_path_guard.go`:
+
+```go
+package services
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+func ResolveWorkspacePath(workspaceRoot, relativePath string) (string, error) {
+ workspaceRoot = filepath.Clean(workspaceRoot)
+ cleanRelative := filepath.Clean("/" + strings.TrimSpace(relativePath))
+ cleanRelative = strings.TrimPrefix(cleanRelative, string(filepath.Separator))
+ fullPath := filepath.Join(workspaceRoot, cleanRelative)
+
+ rootReal, err := filepath.EvalSymlinks(workspaceRoot)
+ if err != nil {
+ return "", err
+ }
+ parent := fullPath
+ if info, statErr := os.Lstat(fullPath); statErr == nil && !info.IsDir() {
+ parent = filepath.Dir(fullPath)
+ }
+ if _, statErr := os.Lstat(parent); statErr == nil {
+ realParent, evalErr := filepath.EvalSymlinks(parent)
+ if evalErr != nil {
+ return "", evalErr
+ }
+ if !isPathInside(rootReal, realParent) {
+ return "", fmt.Errorf("workspace path escapes instance workspace")
+ }
+ }
+ if !isPathInside(workspaceRoot, fullPath) {
+ return "", fmt.Errorf("workspace path escapes instance workspace")
+ }
+ return fullPath, nil
+}
+
+func isPathInside(root, candidate string) bool {
+ rel, err := filepath.Rel(root, candidate)
+ if err != nil {
+ return false
+ }
+ return rel == "." || (!strings.HasPrefix(rel, ".."+string(filepath.Separator)) && rel != "..")
+}
+```
+
+- [ ] **Step 3: Write workspace service tests**
+
+Create `backend/internal/services/workspace_file_service_test.go`:
+
+```go
+func TestWorkspaceFileServicePreviewTextLimit(t *testing.T) {
+ root := t.TempDir()
+ if err := os.WriteFile(filepath.Join(root, "small.txt"), []byte("hello"), 0640); err != nil {
+ t.Fatal(err)
+ }
+ service := NewWorkspaceFileService(fakeAuditRepo{})
+ preview, err := service.Preview(context.Background(), WorkspaceFileScope{InstanceID: 1, UserID: 2, WorkspacePath: root}, "small.txt")
+ if err != nil {
+ t.Fatalf("Preview returned error: %v", err)
+ }
+ if preview.Kind != "text" || preview.Text != "hello" {
+ t.Fatalf("unexpected preview %#v", preview)
+ }
+}
+
+func TestWorkspaceFileServiceRejectsLargeTextPreview(t *testing.T) {
+ root := t.TempDir()
+ large := bytes.Repeat([]byte("a"), 1024*1024+1)
+ if err := os.WriteFile(filepath.Join(root, "large.log"), large, 0640); err != nil {
+ t.Fatal(err)
+ }
+ service := NewWorkspaceFileService(fakeAuditRepo{})
+ _, err := service.Preview(context.Background(), WorkspaceFileScope{InstanceID: 1, UserID: 2, WorkspacePath: root}, "large.log")
+ if err == nil || err.Error() != "text preview exceeds 1 MiB" {
+ t.Fatalf("unexpected error %v", err)
+ }
+}
+```
+
+- [ ] **Step 4: Implement workspace file service**
+
+Create `backend/internal/services/workspace_file_service.go` with these exported types:
+
+```go
+type WorkspaceFileScope struct {
+ InstanceID int
+ UserID int
+ WorkspacePath string
+}
+
+type WorkspaceEntry struct {
+ Name string `json:"name"`
+ Path string `json:"path"`
+ IsDir bool `json:"is_dir"`
+ Size int64 `json:"size"`
+ ModifiedAt time.Time `json:"modified_at"`
+ Previewable bool `json:"previewable"`
+ Downloadable bool `json:"downloadable"`
+}
+
+type WorkspacePreview struct {
+ Kind string `json:"kind"`
+ ContentType string `json:"content_type"`
+ Text string `json:"text,omitempty"`
+ URL string `json:"url,omitempty"`
+}
+
+type WorkspaceFileService interface {
+ List(ctx context.Context, scope WorkspaceFileScope, relativePath string) ([]WorkspaceEntry, error)
+ Preview(ctx context.Context, scope WorkspaceFileScope, relativePath string) (*WorkspacePreview, error)
+ OpenDownload(ctx context.Context, scope WorkspaceFileScope, relativePath string) (*os.File, string, int64, error)
+ Upload(ctx context.Context, scope WorkspaceFileScope, relativeDir string, filename string, reader io.Reader, size int64) error
+ Mkdir(ctx context.Context, scope WorkspaceFileScope, relativePath string) error
+ Rename(ctx context.Context, scope WorkspaceFileScope, oldPath, newPath string) error
+ Delete(ctx context.Context, scope WorkspaceFileScope, relativePath string) error
+}
+```
+
+Rules to implement:
+- Text preview extensions: `.txt`, `.md`, `.json`, `.yaml`, `.yml`, `.log`, `.py`, `.js`, `.ts`, `.go`, `.sh`; max 1 MiB.
+- Image preview extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`; max 10 MiB.
+- PDF preview uses iframe URL and content type `application/pdf`.
+- Unknown binary files are download-only.
+- Upload max is read from env `WORKSPACE_UPLOAD_MAX_BYTES`, default `524288000`.
+- Audit upload, mkdir, rename, delete, and download. Do not audit preview.
+
+- [ ] **Step 5: Implement handler routes**
+
+Create `backend/internal/handlers/workspace_file_handler.go` with endpoints:
+
+```go
+GET /api/v1/instances/:id/workspace/files
+GET /api/v1/instances/:id/workspace/preview
+GET /api/v1/instances/:id/workspace/download
+POST /api/v1/instances/:id/workspace/upload
+POST /api/v1/instances/:id/workspace/folders
+PATCH /api/v1/instances/:id/workspace/entries
+DELETE /api/v1/instances/:id/workspace/entries
+```
+
+Each handler must load the instance, confirm ownership from auth context, require `WorkspacePath != nil`, and create:
+
+```go
+scope := services.WorkspaceFileScope{
+ InstanceID: instance.ID,
+ UserID: userID,
+ WorkspacePath: *instance.WorkspacePath,
+}
+```
+
+- [ ] **Step 6: Wire workspace routes**
+
+In `backend/cmd/server/main.go`:
+
+```go
+workspaceAuditRepo := repository.NewWorkspaceFileAuditRepository(sess)
+workspaceFileService := services.NewWorkspaceFileService(workspaceAuditRepo)
+workspaceFileHandler := handlers.NewWorkspaceFileHandler(instanceService, workspaceFileService)
+
+instances := api.Group("/instances")
+instances.GET("/:id/workspace/files", workspaceFileHandler.List)
+instances.GET("/:id/workspace/preview", workspaceFileHandler.Preview)
+instances.GET("/:id/workspace/download", workspaceFileHandler.Download)
+instances.POST("/:id/workspace/upload", workspaceFileHandler.Upload)
+instances.POST("/:id/workspace/folders", workspaceFileHandler.Mkdir)
+instances.PATCH("/:id/workspace/entries", workspaceFileHandler.Rename)
+instances.DELETE("/:id/workspace/entries", workspaceFileHandler.Delete)
+```
+
+- [ ] **Step 7: Run workspace backend tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/services ./backend/internal/handlers -run 'Workspace|ResolveWorkspacePath' -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 8: Commit workspace backend**
+
+Run:
+
+```powershell
+git add backend/internal/services backend/internal/handlers backend/internal/repository backend/internal/utils backend/cmd/server/main.go
+git commit -m "feat: add workspace file APIs"
+```
+
+## Task 7: Runtime Agent Report And Admin APIs
+
+**Files:**
+- Create: `backend/internal/handlers/runtime_agent_handler.go`
+- Create: `backend/internal/handlers/runtime_pool_handler.go`
+- Create: `backend/internal/handlers/runtime_pool_handler_test.go`
+- Modify: `backend/internal/services/websocket_service.go`
+- Modify: `backend/cmd/server/main.go`
+
+- [ ] **Step 1: Implement runtime agent report handler**
+
+Create `backend/internal/handlers/runtime_agent_handler.go` with:
+
+```go
+type RuntimeAgentHandler struct {
+ cfg config.RuntimeConfig
+ podRepo repository.RuntimePodRepository
+ bindingRepo repository.InstanceRuntimeBindingRepository
+ events services.RuntimeEventService
+}
+
+func (h *RuntimeAgentHandler) requireAgentToken(c *gin.Context) bool {
+ if h.cfg.AgentReportToken == "" || c.GetHeader("X-ClawManager-Agent-Token") != h.cfg.AgentReportToken {
+ utils.Unauthorized(c, "invalid runtime agent token")
+ return false
+ }
+ return true
+}
+```
+
+Add handlers:
+- `Register` upserts `runtime_pods`.
+- `Heartbeat` updates state, used slots, draining, and last seen.
+- `ReportMetrics` updates metrics and binding health, then publishes `runtime_pod_metrics` to Redis events.
+- `ReportGateways` reconciles binding state from agent.
+- `ReportSkills` stores skill reports using existing skill service hooks if available; if no hook exists, accept the request and publish a `runtime_agent_skills_reported` event.
+
+- [ ] **Step 2: Implement admin runtime handler**
+
+Create `backend/internal/handlers/runtime_pool_handler.go`:
+
+```go
+type RuntimePoolHandler struct {
+ podRepo repository.RuntimePodRepository
+ bindingRepo repository.InstanceRuntimeBindingRepository
+ rolloutRepo repository.RuntimeRolloutRepository
+ scheduler *services.RuntimeScheduler
+}
+
+func (h *RuntimePoolHandler) ListPods(c *gin.Context)
+func (h *RuntimePoolHandler) GetPodGateways(c *gin.Context)
+func (h *RuntimePoolHandler) DrainPod(c *gin.Context)
+func (h *RuntimePoolHandler) StartRollout(c *gin.Context)
+```
+
+`ListPods` returns:
+
+```json
+{
+ "pods": [
+ {
+ "id": 9,
+ "runtime_type": "openclaw",
+ "pod_name": "openclaw-runtime-abcde",
+ "pod_ip": "10.42.0.31",
+ "node_name": "node-a",
+ "state": "ready",
+ "used_slots": 37,
+ "capacity": 100,
+ "draining": false,
+ "cpu_millis_used": 13600,
+ "memory_bytes_used": 42949672960,
+ "disk_bytes_used": 214748364800,
+ "network_rx_bytes": 9223372,
+ "network_tx_bytes": 19223372,
+ "last_seen_at": "2026-06-01T10:00:00Z"
+ }
+ ]
+}
+```
+
+- [ ] **Step 3: Add admin handler tests**
+
+Create `backend/internal/handlers/runtime_pool_handler_test.go` and verify non-admin access is rejected and admin access returns metrics. Use existing auth middleware test helpers if present; otherwise call the handler directly with `gin.CreateTestContext`.
+
+- [ ] **Step 4: Extend websocket service**
+
+Modify `backend/internal/services/websocket_service.go`:
+
+```go
+type WebSocketTopic string
+
+const (
+ WebSocketTopicUser WebSocketTopic = "user"
+ WebSocketTopicRuntimeAdmin WebSocketTopic = "runtime_admin"
+)
+```
+
+Add subscription filtering:
+
+```go
+type Client struct {
+ UserID int
+ Role string
+ Topic WebSocketTopic
+ Send chan []byte
+}
+
+func (h *Hub) BroadcastRuntimeAdmin(message []byte) {
+ h.mu.RLock()
+ defer h.mu.RUnlock()
+ for client := range h.clients {
+ if client.Role == "admin" && client.Topic == WebSocketTopicRuntimeAdmin {
+ select {
+ case client.Send <- message:
+ default:
+ }
+ }
+ }
+}
+```
+
+Start one goroutine per backend replica to `XREAD` `clawmanager:runtime-events` and broadcast runtime admin messages to local websocket clients.
+
+- [ ] **Step 5: Wire routes**
+
+In `backend/cmd/server/main.go`:
+
+```go
+runtimeAgentHandler := handlers.NewRuntimeAgentHandler(cfg.Runtime, runtimePodRepo, bindingRepo, runtimeEvents)
+api.POST("/runtime-agent/register", runtimeAgentHandler.Register)
+api.POST("/runtime-agent/heartbeat", runtimeAgentHandler.Heartbeat)
+api.POST("/runtime-agent/gateways/report", runtimeAgentHandler.ReportGateways)
+api.POST("/runtime-agent/skills/report", runtimeAgentHandler.ReportSkills)
+api.POST("/runtime-agent/metrics/report", runtimeAgentHandler.ReportMetrics)
+
+runtimePoolHandler := handlers.NewRuntimePoolHandler(runtimePodRepo, bindingRepo, rolloutRepo, runtimeScheduler)
+admin.GET("/runtime-pods", runtimePoolHandler.ListPods)
+admin.GET("/runtime-pods/:id/gateways", runtimePoolHandler.GetPodGateways)
+admin.POST("/runtime-pods/:id/drain", runtimePoolHandler.DrainPod)
+admin.POST("/runtime-rollouts", runtimePoolHandler.StartRollout)
+```
+
+- [ ] **Step 6: Run admin API tests**
+
+Run:
+
+```powershell
+go test ./backend/internal/handlers ./backend/internal/services -run 'RuntimePool|RuntimeAgent|WebSocket' -count=1
+```
+
+Expected: pass.
+
+- [ ] **Step 7: Commit admin runtime APIs**
+
+Run:
+
+```powershell
+git add backend/internal/handlers backend/internal/services backend/cmd/server/main.go
+git commit -m "feat: add runtime admin APIs"
+```
+
+## Task 8: Frontend Simple UI Foundation
+
+**Files:**
+- Modify: `frontend/package.json`
+- Modify: package lock file if present after install.
+- Modify: `frontend/src/index.css`
+- Modify: `frontend/src/components/UserLayout.tsx`
+- Modify: `frontend/src/components/AdminLayout.tsx`
+- Modify: `frontend/src/App.css` if it still injects decorative gradients.
+
+- [ ] **Step 1: Add icon dependency**
+
+Run:
+
+```powershell
+cd frontend
+npm install lucide-react
+cd ..
+```
+
+Expected: `frontend/package.json` and the lock file include `lucide-react`.
+
+- [ ] **Step 2: Replace global visual tokens**
+
+Modify `frontend/src/index.css` so the design uses a neutral, simple base:
+
+```css
+:root {
+ font-family:
+ Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
+ sans-serif;
+ color: #111827;
+ background: #f7f8fa;
+ font-synthesis: none;
+ text-rendering: optimizeLegibility;
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+ margin: 0;
+ min-width: 320px;
+ min-height: 100vh;
+ background: #f7f8fa;
+}
+
+button,
+input,
+select,
+textarea {
+ font: inherit;
+}
+
+.cm-surface {
+ background: #ffffff;
+ border: 1px solid #e5e7eb;
+ border-radius: 8px;
+}
+
+.cm-button {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ gap: 6px;
+ min-height: 36px;
+ border-radius: 6px;
+ border: 1px solid #d1d5db;
+ background: #ffffff;
+ color: #111827;
+}
+
+.cm-button-primary {
+ border-color: #2563eb;
+ background: #2563eb;
+ color: #ffffff;
+}
+```
+
+Remove decorative gradient or orb classes from `App.css`.
+
+- [ ] **Step 3: Simplify user layout**
+
+Modify `frontend/src/components/UserLayout.tsx`:
+- Use a plain top bar and left nav.
+- Keep border radius at `rounded-lg` or smaller.
+- Use `lucide-react` icons for nav and command buttons.
+- Remove runtime details from ordinary user navigation labels.
+- Keep language switcher and account actions.
+
+Use this layout shape:
+
+```tsx
+
+
+
+
+ ...
+
+
+
+
+
+```
+
+- [ ] **Step 4: Simplify admin layout**
+
+Modify `frontend/src/components/AdminLayout.tsx` with the same visual system and add a nav entry:
+
+```tsx
+{
+ to: "/admin/runtime-pods",
+ label: "Runtime Pods",
+ icon: Server,
+}
+```
+
+Do not expose admin-only runtime metrics in `UserLayout`.
+
+- [ ] **Step 5: Run frontend lint**
+
+Run:
+
+```powershell
+cd frontend
+npm run lint
+cd ..
+```
+
+Expected: pass.
+
+- [ ] **Step 6: Commit UI foundation**
+
+Run:
+
+```powershell
+git add frontend/package.json frontend/package-lock.json frontend/src/index.css frontend/src/App.css frontend/src/components/UserLayout.tsx frontend/src/components/AdminLayout.tsx
+git commit -m "style: simplify ClawManager UI shell"
+```
+
+## Task 9: Frontend Workspace Manager And V2 User Pages
+
+**Files:**
+- Modify: `frontend/src/types/instance.ts`
+- Create: `frontend/src/types/workspace.ts`
+- Create: `frontend/src/services/workspaceService.ts`
+- Create: `frontend/src/components/WorkspaceFileManager.tsx`
+- Create: `frontend/src/components/InstanceServiceFrame.tsx`
+- Modify: `frontend/src/pages/instances/CreateInstancePage.tsx`
+- Modify: `frontend/src/pages/instances/InstanceListPage.tsx`
+- Modify: `frontend/src/pages/instances/InstanceDetailPage.tsx`
+- Modify: `frontend/src/services/instanceService.ts`
+
+- [ ] **Step 1: Add TypeScript types**
+
+Create `frontend/src/types/workspace.ts`:
+
+```ts
+export interface WorkspaceEntry {
+ name: string;
+ path: string;
+ is_dir: boolean;
+ size: number;
+ modified_at: string;
+ previewable: boolean;
+ downloadable: boolean;
+}
+
+export interface WorkspacePreview {
+ kind: "text" | "image" | "pdf" | "download";
+ content_type: string;
+ text?: string;
+ url?: string;
+}
+```
+
+Modify `frontend/src/types/instance.ts`:
+
+```ts
+export type V2InstanceType = "openclaw" | "hermes";
+export type InstanceAvailability = "available" | "starting" | "unavailable";
+
+export interface InstanceStatus {
+ instance_id: number;
+ status: string;
+ availability?: InstanceAvailability;
+ agent_type?: V2InstanceType;
+ workspace_usage_bytes?: number;
+ created_at?: string;
+ started_at?: string;
+}
+```
+
+Keep legacy optional Pod fields only if existing pages still need them for admin legacy screens.
+
+- [ ] **Step 2: Add workspace service**
+
+Create `frontend/src/services/workspaceService.ts`:
+
+```ts
+import api from "./api";
+import type { WorkspaceEntry, WorkspacePreview } from "../types/workspace";
+
+export const workspaceService = {
+ async list(instanceId: number, path = ""): Promise {
+ const response = await api.get(`/instances/${instanceId}/workspace/files`, {
+ params: { path },
+ });
+ return response.data.data.entries;
+ },
+
+ async preview(instanceId: number, path: string): Promise {
+ const response = await api.get(`/instances/${instanceId}/workspace/preview`, {
+ params: { path },
+ });
+ return response.data.data.preview;
+ },
+
+ downloadUrl(instanceId: number, path: string): string {
+ return `/api/v1/instances/${instanceId}/workspace/download?path=${encodeURIComponent(path)}`;
+ },
+
+ async upload(instanceId: number, path: string, file: File): Promise {
+ const formData = new FormData();
+ formData.append("file", file);
+ await api.post(`/instances/${instanceId}/workspace/upload`, formData, {
+ params: { path },
+ headers: { "Content-Type": "multipart/form-data" },
+ });
+ },
+
+ async mkdir(instanceId: number, path: string): Promise {
+ await api.post(`/instances/${instanceId}/workspace/folders`, { path });
+ },
+
+ async rename(instanceId: number, oldPath: string, newPath: string): Promise {
+ await api.patch(`/instances/${instanceId}/workspace/entries`, {
+ old_path: oldPath,
+ new_path: newPath,
+ });
+ },
+
+ async remove(instanceId: number, path: string): Promise {
+ await api.delete(`/instances/${instanceId}/workspace/entries`, {
+ params: { path },
+ });
+ },
+};
+```
+
+- [ ] **Step 3: Build independent file manager**
+
+Create `frontend/src/components/WorkspaceFileManager.tsx`. It must:
+- Fetch entries with React Query.
+- Show breadcrumb path.
+- Upload via hidden file input.
+- Provide icon buttons for preview, download, rename, delete, and new folder.
+- Show text preview in a compact preformatted pane.
+- Show image/PDF preview in a modal or right panel.
+- Never render an arbitrary path input that can bypass the breadcrumb.
+
+Core state:
+
+```tsx
+const [currentPath, setCurrentPath] = useState("");
+const [previewPath, setPreviewPath] = useState(null);
+const entriesQuery = useQuery({
+ queryKey: ["workspace", instanceId, currentPath],
+ queryFn: () => workspaceService.list(instanceId, currentPath),
+});
+```
+
+- [ ] **Step 4: Build service frame**
+
+Create `frontend/src/components/InstanceServiceFrame.tsx`:
+
+```tsx
+interface InstanceServiceFrameProps {
+ instanceId: number;
+ availability: "available" | "starting" | "unavailable";
+}
+
+export function InstanceServiceFrame({ instanceId, availability }: InstanceServiceFrameProps) {
+ if (availability === "starting") {
+ return Starting;
+ }
+ if (availability === "unavailable") {
+ return Unavailable;
+ }
+ return (
+
+ );
+}
+```
+
+- [ ] **Step 5: Restrict create page to V2 types**
+
+Modify `frontend/src/pages/instances/CreateInstancePage.tsx` so the visible type choices are only:
+
+```ts
+const CREATE_INSTANCE_TYPES = INSTANCE_TYPES.filter((type) =>
+ ["openclaw", "hermes"].includes(type.id),
+);
+```
+
+Mark existing non-V2 types as legacy only in admin/history contexts, not in creation.
+
+- [ ] **Step 6: Simplify ordinary user list and detail pages**
+
+Modify `InstanceListPage.tsx` and `InstanceDetailPage.tsx`:
+- Remove service resource, recent status, Pod name, Pod IP, namespace, service, gateway port, scheduler details from ordinary user pages.
+- Show status as `Available`, `Starting`, or `Unavailable`.
+- Show instance type, name, updated time, and workspace usage.
+- Put `InstanceServiceFrame` and `WorkspaceFileManager` in tabs or a split layout.
+- Keep start, stop, restart, delete actions.
+
+Detail page core:
+
+```tsx
+const availability =
+ status?.availability ??
+ (instance.status === "running" ? "available" : instance.status === "creating" ? "starting" : "unavailable");
+
+return (
+
+
+
+ {instance.name}
+ {instance.type === "hermes" ? "Hermes" : "OpenClaw"}
+
+
+
+
+
+);
+```
+
+- [ ] **Step 7: Run frontend checks**
+
+Run:
+
+```powershell
+cd frontend
+npm run lint
+npm run build
+cd ..
+```
+
+Expected: both commands pass.
+
+- [ ] **Step 8: Commit user V2 UI**
+
+Run:
+
+```powershell
+git add frontend/src/types frontend/src/services frontend/src/components frontend/src/pages/instances
+git commit -m "feat: add V2 user workspace UI"
+```
+
+## Task 10: Admin Runtime Pods And Rollout UI
+
+**Files:**
+- Create: `frontend/src/types/runtimePool.ts`
+- Create: `frontend/src/services/runtimePoolService.ts`
+- Modify: `frontend/src/hooks/useWebSocket.ts`
+- Create: `frontend/src/pages/admin/RuntimePodsPage.tsx`
+- Modify: `frontend/src/pages/admin/SystemSettingsPage.tsx`
+- Modify: `frontend/src/router/index.tsx`
+- Modify: `frontend/src/components/AdminLayout.tsx`
+
+- [ ] **Step 1: Add runtime pool types**
+
+Create `frontend/src/types/runtimePool.ts`:
+
+```ts
+export interface RuntimePod {
+ id: number;
+ runtime_type: "openclaw" | "hermes";
+ pod_name: string;
+ pod_ip?: string;
+ node_name?: string;
+ state: "pending" | "ready" | "draining" | "unhealthy" | "deleted";
+ used_slots: number;
+ capacity: number;
+ draining: boolean;
+ cpu_millis_used: number;
+ memory_bytes_used: number;
+ disk_bytes_used: number;
+ network_rx_bytes: number;
+ network_tx_bytes: number;
+ last_seen_at?: string;
+}
+
+export interface RuntimeGateway {
+ instance_id: number;
+ gateway_id: string;
+ gateway_port: number;
+ state: string;
+ workspace_path: string;
+ last_health_at?: string;
+}
+
+export interface StartRuntimeRolloutRequest {
+ runtime_type: "openclaw" | "hermes";
+ target_image_ref: string;
+ batch_size: number;
+ max_unavailable: number;
+}
+```
+
+- [ ] **Step 2: Add admin service client**
+
+Create `frontend/src/services/runtimePoolService.ts`:
+
+```ts
+import api from "./api";
+import type { RuntimeGateway, RuntimePod, StartRuntimeRolloutRequest } from "../types/runtimePool";
+
+export const runtimePoolService = {
+ async listPods(runtimeType?: "openclaw" | "hermes"): Promise {
+ const response = await api.get("/admin/runtime-pods", {
+ params: runtimeType ? { runtime_type: runtimeType } : undefined,
+ });
+ return response.data.data.pods;
+ },
+
+ async listGateways(podId: number): Promise {
+ const response = await api.get(`/admin/runtime-pods/${podId}/gateways`);
+ return response.data.data.gateways;
+ },
+
+ async drainPod(podId: number): Promise {
+ await api.post(`/admin/runtime-pods/${podId}/drain`);
+ },
+
+ async startRollout(data: StartRuntimeRolloutRequest): Promise {
+ await api.post("/admin/runtime-rollouts", data);
+ },
+};
+```
+
+- [ ] **Step 3: Create Runtime Pods page**
+
+Modify `frontend/src/hooks/useWebSocket.ts` first:
+
+```ts
+export interface RuntimeAdminMessage {
+ type: "runtime_pod_metrics" | "runtime_pod_state" | "runtime_rollout";
+ data: unknown;
+ timestamp: string;
+}
+
+export function useRuntimeAdminWebSocket(
+ onRuntimeEvent?: (message: RuntimeAdminMessage) => void,
+) {
+ const { addMessageHandler, isConnected } = useWebSocket();
+
+ useEffect(() => {
+ if (!onRuntimeEvent) return;
+
+ const handler = (message: WebSocketMessage) => {
+ if (
+ message.type === "runtime_pod_metrics" ||
+ message.type === "runtime_pod_state" ||
+ message.type === "runtime_rollout"
+ ) {
+ onRuntimeEvent(message as RuntimeAdminMessage);
+ }
+ };
+
+ return addMessageHandler(handler);
+ }, [onRuntimeEvent, addMessageHandler]);
+
+ return { isConnected };
+}
+```
+
+Create `frontend/src/pages/admin/RuntimePodsPage.tsx`. It must:
+- Show segmented filter: All, OpenClaw, Hermes.
+- Show a dense table with Pod, type, state, slots, CPU, memory, disk, network, last seen.
+- Refresh with React Query every 3 seconds.
+- Subscribe to admin runtime websocket through `useRuntimeAdminWebSocket`; invalidate the `["runtime-pods"]` query when a runtime event arrives.
+- Provide a Drain button for each Pod.
+- Show a gateway drawer/table for a selected Pod.
+
+Use simple table layout:
+
+```tsx
+
+
+ ...
+
+
+ ...
+
+
+```
+
+- [ ] **Step 4: Add route**
+
+Modify `frontend/src/router/index.tsx`:
+
+```tsx
+{
+ path: "runtime-pods",
+ element: /.cache/e2e/workspaces
+```
+
+Backend runtime env overrides:
+
+```text
+SERVER_ADDRESS=:9001
+DB_HOST=127.0.0.1
+DB_PORT=13307
+DB_USER=root
+DB_PASSWORD=123456
+DB_NAME=clawmanager_e2e
+JWT_SECRET=clawmanager-e2e-secret
+RUNTIME_SCHEDULER_ENABLED=false
+RUNTIME_AGENT_REPORT_TOKEN=e2e-runtime-agent-token
+RUNTIME_WORKSPACE_ROOT=/.cache/e2e/workspaces
+OBJECT_STORAGE_LOCAL_FALLBACK=/.cache/e2e/object-storage
+SKILL_SCANNER_ENABLED=false
+```
+
+## Task 1: Scaffold The E2E Package
+
+**Files:**
+- Create: `e2e/package.json`
+- Create: `e2e/tsconfig.json`
+- Create: `e2e/.gitignore`
+- Create: `e2e/reports/.gitkeep`
+- Create: `e2e/README.md`
+- Generate: `e2e/package-lock.json`
+
+- [ ] **Step 1: Create package metadata and scripts**
+
+Create `e2e/package.json`:
+
+```json
+{
+ "name": "clawmanager-e2e",
+ "private": true,
+ "version": "0.0.0",
+ "type": "module",
+ "scripts": {
+ "test:p0": "tsx scripts/run-with-log.ts p0",
+ "test:p1": "tsx scripts/run-with-log.ts p1",
+ "test:p2": "tsx scripts/run-with-log.ts p2",
+ "test:all": "tsx scripts/run-with-log.ts all",
+ "ci:p0": "tsx scripts/run-with-log.ts p0 --ci",
+ "pw:p0": "playwright test --grep @p0",
+ "pw:p1": "playwright test --grep @p1",
+ "pw:p2": "playwright test --grep @p2",
+ "pw:all": "playwright test",
+ "test:report": "playwright show-report playwright-report",
+ "db:reset": "tsx scripts/reset-db.ts"
+ },
+ "devDependencies": {
+ "@playwright/test": "^1.49.1",
+ "@types/node": "^24.12.0",
+ "mysql2": "^3.11.5",
+ "tsx": "^4.19.2",
+ "typescript": "^5.9.3"
+ }
+}
+```
+
+- [ ] **Step 2: Create TypeScript config**
+
+Create `e2e/tsconfig.json`:
+
+```json
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "strict": true,
+ "types": ["node", "@playwright/test"],
+ "esModuleInterop": true,
+ "forceConsistentCasingInFileNames": true,
+ "skipLibCheck": true,
+ "resolveJsonModule": true,
+ "noEmit": true
+ },
+ "include": ["**/*.ts"]
+}
+```
+
+- [ ] **Step 3: Create ignores and report marker**
+
+Create `e2e/.gitignore`:
+
+```gitignore
+node_modules/
+playwright-report/
+test-results/
+reports/*
+!reports/.gitkeep
+.auth/
+.cache/
+```
+
+Create empty file `e2e/reports/.gitkeep`.
+
+- [ ] **Step 4: Create README**
+
+Create `e2e/README.md` with:
+
+```markdown
+# ClawManager E2E
+
+This directory contains Playwright-based TypeScript e2e tests.
+
+## First-Time Setup
+
+```bash
+npm ci
+npx playwright install chromium
+```
+
+## Run Locally
+
+```bash
+npm run test:p0
+npm run test:report
+```
+
+The default local gate is P0. P1, P2, and all tests are explicit:
+
+```bash
+npm run test:p1
+npm run test:p2
+npm run test:all
+```
+
+## Reports
+
+- Live progress appears in the terminal.
+- Run log: `reports/run.log`
+- JSON: `reports/results.json`
+- JUnit: `reports/junit.xml`
+- HTML: `playwright-report/`
+- Raw artifacts: `test-results/`
+```
+
+- [ ] **Step 5: Install dependencies and generate lockfile**
+
+Run:
+
+```powershell
+npm install
+```
+
+Working directory: `e2e`.
+
+Expected: `package-lock.json` is generated and npm exits with code 0.
+
+- [ ] **Step 6: Commit scaffold**
+
+Run:
+
+```powershell
+git add e2e/package.json e2e/package-lock.json e2e/tsconfig.json e2e/.gitignore e2e/README.md e2e/reports/.gitkeep
+git commit -m "test: scaffold e2e package"
+```
+
+## Task 2: Add Environment, API, And Page Object Modules
+
+**Files:**
+- Create: `e2e/fixtures/env.ts`
+- Create: `e2e/fixtures/users.ts`
+- Create: `e2e/fixtures/apiClient.ts`
+- Create: `e2e/fixtures/test.ts`
+- Create: `e2e/pages/LoginPage.ts`
+- Create: `e2e/pages/AdminRuntimePodsPage.ts`
+
+- [ ] **Step 1: Create environment helper**
+
+Create `e2e/fixtures/env.ts` with typed parsing for URLs, database config, runtime token, workspace root, and CI flag. It must export `env`, `repoRoot`, `e2eRoot`, and `reportsDir`.
+
+- [ ] **Step 2: Create user constants**
+
+Create `e2e/fixtures/users.ts`:
+
+```typescript
+export const users = {
+ admin: {
+ username: "admin",
+ password: "admin123",
+ role: "admin",
+ storageState: ".auth/admin.json"
+ }
+} as const;
+```
+
+- [ ] **Step 3: Create API client helper**
+
+Create `e2e/fixtures/apiClient.ts` with helpers:
+
+```typescript
+export interface LoginTokens {
+ access_token: string;
+ refresh_token: string;
+ expires_in: number;
+}
+
+export async function login(request: APIRequestContext, user = users.admin): Promise;
+export async function getMe(request: APIRequestContext, accessToken: string): Promise<{ username: string; role: string }>;
+export async function registerRuntimePod(request: APIRequestContext, overrides?: Partial): Promise;
+export async function sendRuntimeHeartbeat(request: APIRequestContext, identity: RuntimePodIdentity, overrides?: Partial): Promise;
+export async function listRuntimePods(request: APIRequestContext, accessToken: string): Promise;
+```
+
+The implementation must centralize the `X-ClawManager-Agent-Token` header and never log token values.
+
+- [ ] **Step 4: Create shared Playwright export**
+
+Create `e2e/fixtures/test.ts`:
+
+```typescript
+import { test as base, expect } from "@playwright/test";
+import { env } from "./env";
+
+export const test = base.extend({
+ baseURL: async ({}, use) => {
+ await use(env.frontendUrl);
+ }
+});
+
+export { expect };
+```
+
+- [ ] **Step 5: Create page objects**
+
+Create `e2e/pages/LoginPage.ts` with `goto()`, `login(username, password)`, and `expectVisible()`.
+
+Create `e2e/pages/AdminRuntimePodsPage.ts` with `goto()`, `expectEmptyState()`, and `expectPodVisible(podName)`.
+
+- [ ] **Step 6: Type-check helper modules**
+
+Run:
+
+```powershell
+npx tsc --noEmit
+```
+
+Working directory: `e2e`.
+
+Expected: TypeScript exits with code 0.
+
+- [ ] **Step 7: Commit reusable modules**
+
+Run:
+
+```powershell
+git add e2e/fixtures e2e/pages
+git commit -m "test: add reusable e2e modules"
+```
+
+## Task 3: Add Docker And Lifecycle Scripts
+
+**Files:**
+- Create: `e2e/docker/docker-compose.e2e.yml`
+- Create: `e2e/scripts/reset-db.ts`
+- Create: `e2e/scripts/wait-for.ts`
+- Create: `e2e/scripts/run-with-log.ts`
+- Create: `e2e/scripts/e2e-up.ps1`
+- Create: `e2e/scripts/e2e-down.ps1`
+- Create: `e2e/scripts/e2e-up.sh`
+- Create: `e2e/scripts/e2e-down.sh`
+
+- [ ] **Step 1: Add MySQL compose file**
+
+Create `e2e/docker/docker-compose.e2e.yml` with a MySQL 8 service named `mysql`, host port `13307`, root password `123456`, database `clawmanager_e2e`, and a healthcheck using `mysqladmin ping`.
+
+- [ ] **Step 2: Add database reset script**
+
+Create `e2e/scripts/reset-db.ts` that connects to MySQL without selecting a database, drops `clawmanager_e2e`, creates it with `utf8mb4_unicode_ci`, and exits with a non-zero code on failure.
+
+- [ ] **Step 3: Add readiness helpers**
+
+Create `e2e/scripts/wait-for.ts` exporting `waitForTcpPort`, `waitForHttpStatus`, and `sleep`.
+
+- [ ] **Step 4: Add run-with-log orchestrator**
+
+Create `e2e/scripts/run-with-log.ts` that:
+
+1. Parses suite argument `p0`, `p1`, `p2`, or `all`.
+2. Creates `reports/run.log`.
+3. Starts Docker Compose MySQL.
+4. Runs `reset-db.ts`.
+5. Starts backend with e2e env.
+6. Waits for backend port `9001`.
+7. Starts frontend on `127.0.0.1:9002`.
+8. Waits for frontend HTTP 200.
+9. Runs `npx playwright test` with the requested suite.
+10. Writes terminal output to both console and `reports/run.log`.
+11. Stops backend, frontend, and Docker Compose in `finally`.
+
+- [ ] **Step 5: Add platform helper scripts**
+
+Create PowerShell and shell wrappers that run Docker Compose up/down for local manual control:
+
+```powershell
+docker compose -f docker/docker-compose.e2e.yml up -d mysql
+```
+
+```bash
+docker compose -f docker/docker-compose.e2e.yml up -d mysql
+```
+
+The down scripts should run Docker Compose `down --remove-orphans`.
+
+- [ ] **Step 6: Verify DB reset can run**
+
+Run:
+
+```powershell
+docker compose -f docker/docker-compose.e2e.yml up -d mysql
+npm run db:reset
+docker compose -f docker/docker-compose.e2e.yml down --remove-orphans
+```
+
+Working directory: `e2e`.
+
+Expected: database reset succeeds.
+
+- [ ] **Step 7: Commit lifecycle scripts**
+
+Run:
+
+```powershell
+git add e2e/docker e2e/scripts
+git commit -m "test: add e2e lifecycle scripts"
+```
+
+## Task 4: Add Playwright Configuration And Setup Projects
+
+**Files:**
+- Create: `e2e/playwright.config.ts`
+- Create: `e2e/setup/auth.setup.ts`
+- Create: `e2e/setup/db.setup.ts`
+
+- [ ] **Step 1: Add Playwright config**
+
+Create `e2e/playwright.config.ts` with:
+
+- `testDir: "./tests"`
+- reporters: `list`, `html`, `json`, `junit`
+- output dir `test-results`
+- HTML report dir `playwright-report`
+- retries `1` in CI, `0` locally
+- Chromium project
+- setup projects `auth setup` and `db setup`
+- storage state path `.auth/admin.json` for UI projects that require admin auth
+
+- [ ] **Step 2: Add auth setup**
+
+Create `e2e/setup/auth.setup.ts`. It should login through the UI using `LoginPage`, verify localStorage has `access_token`, and write `.auth/admin.json`.
+
+- [ ] **Step 3: Add runtime pod setup**
+
+Create `e2e/setup/db.setup.ts`. It should call `registerRuntimePod` once with pod name `e2e-openclaw-runtime-p0`, namespace `clawmanager-e2e`, runtime type `openclaw`, state `ready`, capacity `100`, used slots `0`, and image `e2e/openclaw:latest`.
+
+- [ ] **Step 4: Verify Playwright list command**
+
+Run:
+
+```powershell
+npx playwright test --list
+```
+
+Working directory: `e2e`.
+
+Expected: setup projects are listed and no config parse error occurs.
+
+- [ ] **Step 5: Commit config and setup**
+
+Run:
+
+```powershell
+git add e2e/playwright.config.ts e2e/setup
+git commit -m "test: configure e2e playwright setup"
+```
+
+## Task 5: Add P0 API Tests
+
+**Files:**
+- Create: `e2e/tests/api/auth.spec.ts`
+- Create: `e2e/tests/api/runtime-agent.spec.ts`
+
+- [ ] **Step 1: Add auth API tests**
+
+Create `auth.spec.ts` with P0 tests:
+
+- `@p0 auth login returns tokens`
+- `@p0 auth me returns current user with valid token`
+- `@p0 auth me rejects unauthenticated requests`
+
+Use `apiClient.login` and `apiClient.getMe`.
+
+- [ ] **Step 2: Add runtime-agent API tests**
+
+Create `runtime-agent.spec.ts` with P0 tests:
+
+- `@p0 runtime-agent register persists an openclaw runtime pod`
+- `@p0 runtime-agent heartbeat updates pod health state`
+- `@p0 runtime-agent register rejects unsupported runtime type`
+
+Use `apiClient.registerRuntimePod` and `apiClient.sendRuntimeHeartbeat`.
+
+- [ ] **Step 3: Run P0 API tests**
+
+Run:
+
+```powershell
+npm run test:p0 -- --grep "auth|runtime-agent"
+```
+
+Working directory: `e2e`.
+
+Expected: API tests pass after services start.
+
+- [ ] **Step 4: Commit API tests**
+
+Run:
+
+```powershell
+git add e2e/tests/api
+git commit -m "test: add p0 e2e api coverage"
+```
+
+## Task 6: Add P0 UI Tests
+
+**Files:**
+- Create: `e2e/tests/smoke/login.spec.ts`
+- Create: `e2e/tests/smoke/navigation.spec.ts`
+- Create: `e2e/tests/admin/access-control.spec.ts`
+- Create: `e2e/tests/admin/runtime-pods.spec.ts`
+
+- [ ] **Step 1: Add login smoke tests**
+
+Create tests for:
+
+- `@p0 login page renders`
+- `@p0 admin can log in`
+- `@p0 failed login shows an error`
+
+Use `LoginPage`.
+
+- [ ] **Step 2: Add navigation tests**
+
+Create tests for:
+
+- `@p0 unauthenticated users are redirected to login`
+- `@p0 authenticated admin reaches admin dashboard`
+- `@p0 authenticated admin can reach instances and runtime pods routes`
+
+Use storage state from `.auth/admin.json`.
+
+- [ ] **Step 3: Add access control tests**
+
+Create tests for:
+
+- `@p0 unauthenticated admin route redirects to login`
+- `@p0 admin can open runtime pods route`
+
+- [ ] **Step 4: Add runtime Pods UI tests**
+
+Create tests for:
+
+- `@p0 admin runtime pods page renders no runtime pods when unseeded`
+- `@p0 admin runtime pods page renders seeded runtime pod`
+
+If setup always seeds one pod, implement the empty-state test by directly clearing runtime Pods through `db.setup.ts` helper before visiting the page, then reseed for the seeded-state test.
+
+- [ ] **Step 5: Run P0 UI tests**
+
+Run:
+
+```powershell
+npm run test:p0 -- --grep "login|navigation|runtime pods|access"
+```
+
+Working directory: `e2e`.
+
+Expected: UI tests pass after services start.
+
+- [ ] **Step 6: Commit UI tests**
+
+Run:
+
+```powershell
+git add e2e/tests/smoke e2e/tests/admin
+git commit -m "test: add p0 e2e ui coverage"
+```
+
+## Task 7: Add GitHub Actions E2E Job
+
+**Files:**
+- Modify: `.github/workflows/build.yml`
+
+- [ ] **Step 1: Add workflow dispatch input**
+
+Modify `.github/workflows/build.yml` to add `workflow_dispatch` with `e2e_suite` choices `p0`, `p1`, `p2`, and `all`, defaulting to `p0`.
+
+- [ ] **Step 2: Add e2e-p0 job**
+
+Add job `e2e-p0`:
+
+- `runs-on: ubuntu-latest`
+- `needs: [frontend, backend]`
+- checkout
+- setup Node 20 with cache for `e2e/package-lock.json`
+- setup Go using `backend/go.mod`
+- install frontend deps with `npm ci` in `frontend`
+- install e2e deps with `npm ci` in `e2e`
+- install Chromium with `npx playwright install --with-deps chromium`
+- run selected suite. For PRs use `npm run ci:p0`; for manual dispatch map `e2e_suite` to the requested command.
+- upload `e2e/playwright-report`, `e2e/test-results`, and `e2e/reports` on failure.
+
+- [ ] **Step 3: Validate workflow syntax**
+
+Run:
+
+```powershell
+git diff -- .github/workflows/build.yml
+```
+
+Expected: e2e job is present, YAML indentation is valid on visual inspection, existing jobs are untouched except for workflow triggers.
+
+- [ ] **Step 4: Commit GitHub Actions integration**
+
+Run:
+
+```powershell
+git add .github/workflows/build.yml
+git commit -m "ci: add p0 e2e pr check"
+```
+
+## Task 8: Full P0 Verification
+
+**Files:**
+- Verify all files changed in Tasks 1-7.
+
+- [ ] **Step 1: Run TypeScript check**
+
+Run:
+
+```powershell
+npx tsc --noEmit
+```
+
+Working directory: `e2e`.
+
+Expected: exits with code 0.
+
+- [ ] **Step 2: Run P0 suite**
+
+Run:
+
+```powershell
+npm run ci:p0
+```
+
+Working directory: `e2e`.
+
+Expected: P0 tests pass, `reports/run.log`, `reports/results.json`, `reports/junit.xml`, and `playwright-report/` are generated.
+
+- [ ] **Step 3: Verify report opens**
+
+Run:
+
+```powershell
+npm run test:report -- --host 127.0.0.1
+```
+
+Expected: Playwright report server starts. Stop it after confirming no report generation error.
+
+- [ ] **Step 4: Run repository build checks affected by CI**
+
+Run:
+
+```powershell
+npm run build
+```
+
+Working directory: `frontend`.
+
+Run:
+
+```powershell
+go test ./...
+```
+
+Working directory: `backend`.
+
+Expected: both commands exit with code 0, or any pre-existing failures are reported with exact output.
+
+- [ ] **Step 5: Final status review**
+
+Run:
+
+```powershell
+git status --short
+git log --oneline -5
+```
+
+Expected: only intended files remain changed or all e2e work is committed. Existing unrelated dirty files from before this work remain untouched and unstaged.
+
+## Self-Review Checklist
+
+- Every P0 requirement in the spec maps to a test file.
+- Repeated login and API logic is centralized.
+- Runtime-agent payload construction exists in one helper.
+- URLs and tokens come from `fixtures/env.ts`.
+- Report artifacts match the spec paths.
+- GitHub PR check uses `npm run ci:p0`.
+- Local manual commands are documented.
+- No production frontend/backend code is changed for test convenience.
diff --git a/docs/superpowers/plans/2026-06-04-lite-pro-runtime-rework.md b/docs/superpowers/plans/2026-06-04-lite-pro-runtime-rework.md
new file mode 100644
index 0000000..2b89e54
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-04-lite-pro-runtime-rework.md
@@ -0,0 +1,328 @@
+# Lite / Pro Runtime Rework Plan
+
+## Goal
+
+Rework ClawManager instance modes so users choose between:
+
+- `lite`: shared runtime Pod plus per-instance gateway process.
+- `pro`: dedicated desktop Deployment plus Service plus PVC.
+
+Both modes must keep the same user-facing product capabilities: instance access, AI Gateway, channel management, skill management, workspace import/export, and admin operations. The modes differ only in runtime backend, scheduling, and resource/capacity controls.
+
+## Progress Protocol
+
+Implementation should update this plan as each phase completes. Each phase must include:
+
+- Files changed.
+- Tests or checks run.
+- Known gaps or follow-up work.
+- Whether user-visible behavior changed.
+
+Do not revert unrelated existing workspace changes.
+
+## Architecture Decisions
+
+- User-facing mode is `instance_mode`: `lite` or `pro`.
+- Internal backend remains `runtime_type`: `gateway`, `desktop`, or `shell`.
+- `lite` always maps to `runtime_type = gateway`.
+- `pro` always maps to `runtime_type = desktop`.
+- Frontend should show Lite/Pro and avoid exposing gateway/desktop as ordinary user choices.
+- Scheduler must manage only Lite instances.
+- Dedicated K8s lifecycle must manage only Pro and shell instances.
+- External access should still proxy through ClawManager, not directly expose Pod IP or runtime Pod gateway ports.
+- AI Gateway telemetry must include instance-level and gateway-level identity for Lite so multiple Lite instances on one runtime Pod never mix audit, cost, risk, or trace records.
+
+## Phase 0: Planning
+
+- [x] Create this implementation plan.
+- [x] Confirm dirty worktree impact before each implementation phase.
+
+## Phase 1: Instance Mode Data Model And Routing Boundary
+
+### Backend
+
+- [x] Add migration for `instances.instance_mode ENUM('lite','pro') NOT NULL DEFAULT 'lite'`.
+- [x] Add `InstanceMode` to `models.Instance`.
+- [x] Add constants and helpers:
+ - `InstanceModeLite`
+ - `InstanceModePro`
+ - `RuntimeTypeGateway`
+ - `RuntimeTypeDesktop`
+ - `NormalizeInstanceMode`
+ - `RuntimeTypeForInstanceMode`
+ - `InstanceModeForRuntimeType`
+- [x] Extend create request validation to accept `mode` or `instance_mode`.
+- [x] Preserve backward compatibility:
+ - If request has `runtime_type=gateway`, infer `lite`.
+ - If request has `runtime_type=desktop`, infer `pro`.
+ - If neither is present, default to `lite` for OpenClaw/Hermes unless system config says otherwise.
+- [x] Change create flow:
+ - Lite -> existing gateway-pool creation path.
+ - Pro -> existing dedicated runtime creation path.
+- [x] Change `v2RuntimeTypeForInstance` to return true only for Lite/gateway instances.
+- [x] Change scheduler selectors to require `runtime_type='gateway'` and `instance_mode='lite'`.
+- [x] Change sync service to ignore Lite/gateway and continue managing Pro/shell dedicated workloads.
+
+### Frontend
+
+- [x] Add `mode` / `instance_mode` type fields.
+- [x] Show Lite/Pro selection on create page.
+- [x] Submit `mode` to backend.
+- [ ] Keep runtime image selection compatible with Pro desktop images and Lite runtime pool images.
+
+### Tests
+
+- [x] Unit test Lite create produces `instance_mode=lite`, `runtime_type=gateway`, workspace path.
+- [ ] Unit test Pro create produces `instance_mode=pro`, `runtime_type=desktop`, and does not enter gateway scheduler.
+- [x] Unit test scheduler ignores Pro instances even if workspace_path exists.
+
+## Phase 2: Pro Dedicated Deployment + Service + PVC
+
+### K8s Services
+
+- [x] Add per-instance deployment service, separate from shared runtime pool deployment service.
+- [x] Build Deployment from the existing PodConfig shape:
+ - labels: `instance-id`, `instance-name`, `user-id`, `instance-type`, `runtime-type=desktop`, `managed-by=clawreef`
+ - selector should be immutable and match Service selector.
+ - container name remains `desktop`.
+ - probes, resources, env, envFrom, PVC mounts, config map mounts, SHM, and security mode should match current Pod behavior.
+- [x] Add operations:
+ - Ensure Deployment.
+ - Scale Deployment to 1.
+ - Scale Deployment to 0.
+ - Delete Deployment.
+ - Restart/Rollout restart.
+ - Get Deployment status.
+ - Get active Pod for instance.
+
+### Instance Lifecycle
+
+- [x] Pro create: PVC -> Deployment(replicas=1) -> Service.
+- [x] Pro start: scale Deployment to 1 and ensure Service.
+- [x] Pro stop: scale Deployment to 0, retain PVC and Service.
+- [x] Pro restart: rollout restart or scale 0 -> 1.
+- [x] Pro delete: delete Deployment, Service, PVC, Secrets, ConfigMaps.
+- [x] Sync Pro status from Deployment available replicas instead of raw Pod phase.
+
+### Tests
+
+- [x] K8s fake-client tests for BuildInstanceDeployment.
+- [ ] Lifecycle tests for Pro start/stop/delete paths.
+- [ ] Proxy tests still resolve Pro through stable Service.
+
+## Phase 3: Mode-Specific Capacity And Resource Limits
+
+- [x] Add system-level mode limits:
+ - Lite runtime pod count / gateways per pod / max active instances.
+ - Pro capacity / max active instances / max CPU / max memory / max storage / max GPU.
+- [ ] Consider user-level overrides after system-level support is stable.
+- [x] Enforce Lite capacity before accepting Lite create/start.
+- [x] Enforce Pro capacity before accepting Pro create/start.
+- [x] Treat `pro_capacity = 0` as Pro create/start disabled, while keeping existing Pro instances visible and deletable.
+- [ ] Add admin API to read and update mode limits.
+- [x] Add tests for capacity edge cases.
+
+## Phase 4: External Instance Access
+
+### Data And API
+
+- [x] Add `instance_external_access` table:
+ - `instance_id`
+ - `enabled`
+ - `auth_mode`
+ - `public_slug`
+ - `public_token_hash`
+ - `api_key_hash`
+ - `api_key_prefix`
+ - `expires_at`
+ - `created_by`
+ - `last_used_at`
+ - timestamps
+- [x] Owner APIs:
+ - Enable public link.
+ - Disable external access.
+ - Rotate public link by enabling again.
+ - Create API key.
+ - Revoke current API key by disabling external access.
+ - Set expiration.
+- [ ] Admin APIs:
+ - View external access state.
+ - Revoke external access.
+ - Configure global policy: disabled, api-key-only, public-link-allowed.
+
+### Proxy
+
+- [x] Add public route such as `/public/instances/{slug}/proxy/`.
+- [x] Authenticate by capability URL token or API key.
+- [x] Resolve target with the same Lite/Pro proxy routing:
+ - Lite -> runtime binding and gateway port.
+ - Pro -> stable Service.
+- [ ] Record access audit:
+ - instance_id
+ - instance_mode
+ - runtime_type
+ - gateway_id for Lite
+ - api_key prefix/id if applicable
+ - source IP
+ - user agent
+
+### Tests
+
+- [x] Public link succeeds when enabled and unexpired.
+- [x] Public link fails after expiration.
+- [x] API key succeeds and disabled key fails.
+- [ ] Public link fails after disable/rotate.
+- [ ] Lite and Pro proxy targets remain separated.
+
+### Phase 4 Progress Notes
+
+- Files changed:
+ - `backend/internal/db/migrations/027_add_instance_external_access.sql`
+ - `backend/internal/models/instance_external_access.go`
+ - `backend/internal/repository/instance_external_access_repository.go`
+ - `backend/internal/services/instance_external_access_service.go`
+ - `backend/internal/services/instance_external_access_service_test.go`
+ - `backend/internal/handlers/instance_handler.go`
+ - `backend/cmd/server/main.go`
+- Tests/checks run:
+ - `cd backend; $env:GOCACHE='D:\code\github\ClawManagerV2\.cache\go-build'; go test ./internal/services/k8s ./internal/services ./internal/repository ./internal/handlers -run "(InstanceExternalAccess|ExternalAccess|InstanceDeployment|RuntimeDeployment|InstanceMode|V2|Scheduler|BuildV2|UserSafe|WorkspaceArchive|RuntimeLinuxID|RuntimeWorkspacePath|NormalizeV2RuntimeType|Proxy)" -count=1`
+- Known gaps:
+ - Admin external access policy/revoke APIs are still pending.
+ - Public access audit payload is still pending.
+ - Public proxy separation needs a handler/proxy-level regression test.
+- User-visible behavior:
+ - Instance owners can enable public-link or API-key external access.
+ - Public routes proxy through ClawManager using the existing Lite/Pro proxy resolver.
+
+## Phase 5: AI Gateway Lite Gateway-Level Attribution
+
+- [x] Extend gateway auth context to include:
+ - `instance_id`
+ - `instance_mode`
+ - `runtime_type`
+ - `gateway_id`
+ - `runtime_pod_id`
+ - `user_id`
+- [x] Ensure Lite gateway create injects identity into environment/token.
+- [x] Ensure each Lite gateway has a distinct token or claims set.
+- [x] Extend model invocation, audit event, cost record, and risk hit payloads where needed.
+- [x] Add tests proving gateway attribution fields are populated and stripped before provider calls.
+- [ ] Add integration/e2e test proving two Lite instances on one runtime Pod produce separate invocation records.
+
+### Phase 5 Progress Notes
+
+- Files changed:
+ - `backend/internal/middleware/auth_middleware.go`
+ - `backend/internal/handlers/ai_gateway_handler.go`
+ - `backend/internal/aigateway/service.go`
+ - `backend/internal/aigateway/service_test.go`
+ - `backend/internal/models/model_invocation.go`
+ - `backend/internal/models/audit_event.go`
+ - `backend/internal/models/cost_record.go`
+ - `backend/internal/models/risk_hit.go`
+ - `backend/internal/repository/model_invocation_repository.go`
+ - `backend/internal/repository/audit_event_repository.go`
+ - `backend/internal/repository/cost_record_repository.go`
+ - `backend/internal/repository/risk_hit_repository.go`
+ - `backend/internal/db/migrations/028_add_ai_gateway_runtime_attribution.sql`
+- Tests/checks run:
+ - `cd backend; $env:GOCACHE='D:\code\github\ClawManagerV2\.cache\go-build'; go test ./internal/aigateway ./internal/services/k8s ./internal/services ./internal/repository ./internal/handlers ./internal/middleware -run "(RuntimeAttribution|BuildProvider|InstanceExternalAccess|ExternalAccess|InstanceDeployment|RuntimeDeployment|InstanceMode|V2|Scheduler|BuildV2|UserSafe|WorkspaceArchive|RuntimeLinuxID|RuntimeWorkspacePath|NormalizeV2RuntimeType|Proxy|GatewayAuth)" -count=1`
+- Known gaps:
+ - Full multi-gateway e2e attribution proof is still pending.
+- User-visible behavior:
+ - Admin AI audit/cost records can carry Lite gateway identity instead of only instance ID.
+
+## Phase 6: Unified Channel, Skill, Import/Export For Lite And Pro
+
+- [x] Treat channel and skill management as instance capabilities, not runtime backend features.
+- [x] Lite:
+ - Apply config through runtime agent to gateway.
+ - Inventory reports include `instance_id` and `gateway_id`.
+ - Import/export through shared workspace backend.
+- [x] Pro:
+ - Apply config through instance agent/control plane.
+ - Inventory reports include `instance_id`.
+ - Import/export through dedicated PVC workspace backend or instance agent.
+- [x] Add a workspace backend abstraction:
+ - Lite shared workspace path.
+ - Pro dedicated PVC/workspace path.
+- [x] Keep existing OpenClaw/Hermes import/export API shape.
+- [x] Add tests for Lite and Pro import/export workspace selection.
+
+### Phase 6 Progress Notes
+
+- Files changed:
+ - `backend/internal/services/openclaw_transfer_service.go`
+ - `backend/internal/services/openclaw_transfer_service_test.go`
+ - `backend/cmd/server/main.go`
+- Tests/checks run:
+ - `cd backend; $env:GOCACHE='D:\code\github\ClawManagerV2\.cache\go-build'; go test ./internal/aigateway ./internal/services/k8s ./internal/services ./internal/repository ./internal/handlers ./internal/middleware -run "(RuntimeAttribution|BuildProvider|OpenClawTransfer|WorkspaceSpec|InstanceExternalAccess|ExternalAccess|InstanceDeployment|RuntimeDeployment|InstanceMode|V2|Scheduler|BuildV2|UserSafe|WorkspaceArchive|RuntimeLinuxID|RuntimeWorkspacePath|NormalizeV2RuntimeType|Proxy|GatewayAuth)" -count=1`
+- Known gaps:
+ - Real runtime import/export smoke test still needs a running cluster.
+- User-visible behavior:
+ - Lite and Pro keep the same OpenClaw/Hermes import/export endpoints.
+ - Lite import/export targets its per-instance workspace inside the shared runtime pod.
+
+## Phase 7: Admin Monitoring And Management
+
+### Admin Instances
+
+- [x] Show mode: Lite/Pro.
+- [x] Show runtime backend: gateway/desktop for admins only.
+- [ ] Show external access status.
+- [x] Show AI usage/cost/risk by instance through existing observability surfaces with new attribution fields.
+- [x] Support start, stop, restart, delete, sync for Lite/Pro instances.
+- [ ] Support export, logs, revoke external access directly from admin list.
+
+### Runtime Pools
+
+- [x] Keep Lite runtime Pod view:
+ - runtime Pod status.
+ - used/capacity.
+ - gateway distribution.
+ - drain/migrate/failover.
+- [ ] Add Pro capacity view:
+ - pro_capacity.
+ - running Pro instances.
+ - Deployment status.
+ - Service/PVC summary.
+ - resource usage.
+- [x] Add Pro running/creating/total summary in admin instance page.
+
+### Tests
+
+- [x] Frontend build and targeted lint for changed files.
+- [x] Admin instance page covers both Lite and Pro.
+- [ ] E2E smoke navigation includes mode labels and admin operations.
+
+### Phase 7 Progress Notes
+
+- Files changed:
+ - `frontend/src/pages/admin/InstanceManagementPage.tsx`
+ - `frontend/src/pages/instances/InstanceDetailPage.tsx`
+ - `frontend/src/services/instanceService.ts`
+ - `frontend/src/types/instance.ts`
+- Tests/checks run:
+ - `cd frontend; npx eslint src/pages/admin/InstanceManagementPage.tsx src/pages/instances/InstanceDetailPage.tsx src/services/instanceService.ts src/types/instance.ts`
+ - `cd frontend; npm run build`
+- Known gaps:
+ - Full frontend lint still fails on pre-existing unrelated files.
+ - Admin external access status/revoke actions need a dedicated UI/API policy pass.
+- User-visible behavior:
+ - Admin instance page now has Lite/Pro and backend filters plus mode summary.
+ - Instance detail page now lets owners generate public links/API keys and disable external access.
+
+## Phase 8: Verification
+
+- [x] `cd backend && go test ./... -count=1`
+- [x] `cd frontend && npm run lint` attempted; fails on pre-existing unrelated lint debt.
+- [x] `cd frontend && npx eslint `
+- [x] `cd frontend && npm run build`
+- [ ] YAML parse/dry-run for deployment manifests if changed.
+- [ ] Manual smoke:
+ - Create Lite OpenClaw.
+ - Create Pro OpenClaw.
+ - Access both through ClawManager.
+ - Enable external access for both.
+ - Verify AI Gateway attribution for Lite is instance/gateway-specific.
+ - Verify admin can see/manage both modes.
diff --git a/docs/superpowers/plans/2026-06-04-short-sharelink.md b/docs/superpowers/plans/2026-06-04-short-sharelink.md
new file mode 100644
index 0000000..01e4da0
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-04-short-sharelink.md
@@ -0,0 +1,65 @@
+# Short Share Link Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace exposed public instance URLs with `/s//` short links and add fixed/custom/permanent expiration choices.
+
+**Architecture:** Public links become capability URLs: the plaintext short code is returned only at creation time and only its SHA-256 hash is stored. The backend resolves `/s/:code/*path` to an enabled external access record, rewrites the request to the internal instance proxy path, and proxies the request. The old `/api/v1/public/instances/:slug/proxy` route is removed.
+
+**Tech Stack:** Go/Gin backend, MySQL migrations, React/Vite frontend, existing Kubernetes image build and rollout flow.
+
+---
+
+### Task 1: Backend Short Link Storage and Service Behavior
+
+**Files:**
+- Modify: `backend/internal/models/instance_external_access.go`
+- Modify: `backend/internal/repository/instance_external_access_repository.go`
+- Modify: `backend/internal/services/instance_external_access_service.go`
+- Modify: `backend/internal/services/instance_external_access_service_test.go`
+- Create: `backend/internal/db/migrations/029_add_short_external_access_links.sql`
+
+- [ ] Write tests that public links return `/s//`, do not return `token=`, and persist only a code hash.
+- [ ] Write tests for preset, custom, and permanent expiration resolution.
+- [ ] Add `short_code_hash` storage and lookup repository methods.
+- [ ] Generate random short codes, hash them, and return only the short URL.
+- [ ] Keep API key mode available, but do not make Public Link depend on a separate query token.
+
+### Task 2: Backend Short Link Routing
+
+**Files:**
+- Modify: `backend/cmd/server/main.go`
+- Modify: `backend/internal/handlers/instance_handler.go`
+- Modify: `backend/internal/handlers/instance_handler_test.go`
+- Modify: `deployments/nginx/nginx.conf`
+
+- [ ] Write handler tests proving `/s//` and `/s//assets/app.js` resolve without query tokens.
+- [ ] Remove old `/api/v1/public/instances/:slug...` public routes.
+- [ ] Add root-level `/s/:code` and `/s/:code/*path` routes.
+- [ ] Rewrite short-link request paths to `/api/v1/instances/:id/proxy/...` before using the existing proxy service.
+- [ ] Add an nginx `/s/` proxy location so the SPA does not consume short links.
+
+### Task 3: Frontend Expiration UI
+
+**Files:**
+- Modify: `frontend/src/types/instance.ts`
+- Modify: `frontend/src/services/instanceService.ts`
+- Modify: `frontend/src/pages/instances/InstanceDetailPage.tsx`
+
+- [ ] Add request types for `preset`, `custom`, and `permanent` expiration modes.
+- [ ] Show fixed choices: 1 hour, 24 hours, 7 days, 30 days, custom, permanent.
+- [ ] Default Public Link creation to 24 hours.
+- [ ] Send expiration selection to `POST /instances/:id/external-access/public-link`.
+- [ ] Display the returned short URL and expiration state.
+
+### Task 4: Verification and Deployment
+
+**Files:**
+- No source-only changes beyond Tasks 1-3.
+
+- [ ] Run targeted backend tests for external access and handler routing.
+- [ ] Run `go test ./... -count=1`.
+- [ ] Run frontend lint/build.
+- [ ] Build and push image to `172.16.1.12:5010`.
+- [ ] Roll out `clawmanager-app`.
+- [ ] Verify on the real cluster that generated links use `/s//`, the long public route is not registered, and `/s//assets/...` no longer returns 401.
diff --git a/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md b/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md
new file mode 100644
index 0000000..b1c0fb0
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-01-clawmanager-v2-runtime-pool-design.md
@@ -0,0 +1,719 @@
+# ClawManager V2 Runtime Pool Design
+
+## Overview
+
+ClawManager V2 changes the runtime model from one Kubernetes Pod per user instance to shared runtime pools. A user instance becomes metadata plus a workspace directory plus a gateway subprocess. A runtime Pod hosts one `clawmanager-agent` and many gateway subprocesses.
+
+Runtime pools are split by agent type:
+
+- `openclaw-runtime` Deployment, initially 1 replica.
+- `hermes-runtime` Deployment, initially 1 replica.
+- Each runtime Pod hosts up to 100 gateways by default.
+- The 101st instance of the same type causes ClawManager to scale the matching Deployment.
+
+The user-facing proxy path remains stable:
+
+```text
+/api/v1/instances/{id}/proxy/
+```
+
+Backend proxying uses the active binding:
+
+```text
+instance_id -> runtime_pod.pod_ip + gateway_port
+```
+
+Workspaces use a shared root:
+
+```text
+/workspaces/{runtime}/user-{user_id}/instance-{instance_id}
+```
+
+ClawManager owns scheduling, persistence, proxying, permissions, file APIs, UI, rollout control, and deployment manifests. `clawmanager-agent` owns gateway subprocess lifecycle, port allocation, cgroups, Linux user isolation, health checks, metrics, and gateway logs.
+
+## Deployment Model
+
+V2 keeps the one-command install goal:
+
+```bash
+kubectl apply -f clawmanager-v2.yaml
+```
+
+The YAML includes:
+
+- Namespace, RBAC, ConfigMaps, Secrets, Services, PVCs.
+- MySQL.
+- Redis.
+- ClawManager backend, default 3 replicas.
+- ClawManager frontend/nginx.
+- AI Gateway / control plane.
+- `workspace-store`.
+- `openclaw-runtime` Deployment.
+- `hermes-runtime` Deployment.
+
+The default storage mode is an embedded lightweight shared store, implemented as an NFS/Ganesha-style service:
+
+- `workspace-store` persists data on its own RWO PVC.
+- Backend and runtime Pods mount `/workspaces`.
+- This satisfies one-YAML deployment and runtime Pod failover.
+- `workspace-store` is a lightweight single point. Storage-layer HA is outside the default one-YAML mode and belongs to a future external RWX mode.
+
+Default runtime parameters:
+
+```text
+backend replicas: 3
+openclaw runtime replicas: 1
+hermes runtime replicas: 1
+gateways per runtime pod: 100
+gateway port range per pod: 20000-20099
+scheduler lease renew: 2s
+scheduler failover: 6-8s
+agent heartbeat interval: 2s
+agent unhealthy threshold: 8s
+gateway health interval: 3s
+migration batch size: 10
+redis lock ttl: 30s
+```
+
+All defaults should be configurable through environment variables or ConfigMap entries.
+
+## Persistence And Hot State
+
+MySQL is the only source of truth. Redis is a hot-path accelerator.
+
+MySQL stores:
+
+- Instances.
+- Runtime Pods.
+- Runtime bindings.
+- Runtime rollouts.
+- Workspace audit records.
+- Users, quotas, and permissions.
+
+Redis stores:
+
+- Runtime Pod heartbeat TTLs.
+- Runtime capacity hot cache.
+- Gateway status snapshots.
+- Scheduler event streams.
+- WebSocket fanout.
+- Short locks.
+
+Redis may be lost and rebuilt. On ClawManager restart, the scheduler reconciles MySQL records with agent-reported `/gateways` state.
+
+## Data Model
+
+The existing `instances` table remains the user instance fact table. V2 adds fields or equivalent migration support for:
+
+```text
+workspace_path
+last_error
+```
+
+In V2, resource fields change meaning:
+
+- `cpu_cores`: cgroup CPU quota for one gateway.
+- `memory_gb`: cgroup memory limit for one gateway.
+- `disk_gb`: logical workspace quota.
+
+New `runtime_pods` table:
+
+```text
+id
+runtime_type: openclaw | hermes
+pod_name
+pod_namespace
+pod_ip
+agent_id
+status: ready | draining | unhealthy | offline | retired
+version
+capacity
+used
+port_start
+port_end
+management_url
+management_token_encrypted
+last_heartbeat_at
+created_at
+updated_at
+```
+
+New `instance_runtime_bindings` table:
+
+```text
+id
+instance_id
+runtime_pod_id
+runtime_type
+gateway_port
+workspace_path
+gateway_status: starting | running | stopped | error
+status: active | released | migrating | error
+reason: create | start | stop | failover | upgrade | delete | recovery
+bound_at
+released_at
+last_health_check_at
+last_error
+```
+
+New `runtime_rollouts` table:
+
+```text
+id
+runtime_type
+from_image
+to_image
+status: idle | creating_new_pods | draining_old_pods | migrating_gateways | paused | failed | completed | rolling_back
+strategy
+batch_size
+started_by
+started_at
+completed_at
+paused_at
+error_message
+```
+
+## State Machines
+
+Instance statuses:
+
+```text
+creating -> running gateway scheduled and healthy
+creating -> error workspace, scheduler, or agent failure
+running -> stopped user stops instance; slot and port are released
+running -> running failover or upgrade migration succeeds
+running -> error repeated recovery failure
+running -> deleting
+stopped -> creating user starts instance; scheduler chooses a new Pod
+stopped -> deleting
+error -> creating user retries start
+error -> deleting
+```
+
+Runtime Pod statuses:
+
+```text
+ready accepts new gateways
+draining accepts no new gateways; existing gateways are migrated away
+unhealthy agent or Pod health failure; active bindings migrate away
+offline Pod is unreachable
+retired Pod has no active gateways and can be removed or ignored
+```
+
+## Scheduler
+
+The backend runs as multiple replicas. All replicas serve API traffic, but only the backend holding a Kubernetes `Lease` runs `RuntimeScheduler`.
+
+The scheduler handles:
+
+- Newly created instances in `creating`.
+- Start requests.
+- Stop/Delete cleanup.
+- Runtime Pod capacity changes.
+- Runtime Pod heartbeat timeout.
+- Gateway health failure.
+- Draining Pod migration.
+- Rollout batches.
+- ClawManager restart recovery.
+- Orphan gateway cleanup.
+
+Concurrency protection uses:
+
+- Kubernetes Lease for scheduler leadership.
+- Redis short locks:
+ - `lock:instance:{id}`
+ - `lock:runtime:scale:{type}`
+ - `lock:runtime:pod:{pod_id}`
+ - `lock:workspace:{instance_id}:{path_hash}`
+- Conditional DB updates as the final consistency guard.
+
+## Instance Lifecycle
+
+Create is asynchronous:
+
+1. API creates the instance record with `creating`.
+2. API creates the workspace directory.
+3. API writes a scheduler event to Redis.
+4. Scheduler chooses a `ready` runtime Pod with capacity.
+5. If no Pod has capacity, scheduler scales the matching runtime Deployment.
+6. Scheduler waits for the new agent to register.
+7. Scheduler calls agent `POST /gateways`.
+8. Scheduler writes an active binding.
+9. Scheduler updates the instance to `running`.
+
+Stop:
+
+- Calls agent to delete the gateway.
+- Releases slot and port.
+- Marks active binding `released`.
+- Updates the instance to `stopped`.
+- Leaves workspace data intact.
+
+Start:
+
+- Moves instance to `creating`.
+- Schedules a fresh gateway.
+- May use a different Pod and port.
+
+Restart:
+
+- Prefer restart on the current healthy Pod.
+- If the current Pod is unhealthy, reschedule to a healthy Pod.
+
+Delete:
+
+- Stops the gateway if active.
+- Deletes workspace contents.
+- Deletes or marks instance according to existing repository behavior.
+- Writes audit events.
+
+## Failover
+
+Failover triggers:
+
+- Agent heartbeat exceeds 8 seconds.
+- Pod is NotReady, deleted, or restarted.
+- Gateway health fails repeatedly.
+- Proxy detects active binding is unreachable.
+
+Failover flow:
+
+1. Mark runtime Pod `unhealthy` or `offline`.
+2. Select a healthy same-runtime Pod.
+3. If capacity exists, call target agent `recover`.
+4. If capacity is full, scale the Deployment first.
+5. Write a new active binding.
+6. Release or retire the old binding.
+7. Clean orphan gateway if the old Pod later returns.
+
+Target interruption is 5-10 seconds.
+
+## Gray Upgrade / Rollout
+
+OpenClaw and Hermes upgrades use the same drain-and-migrate machinery as failover.
+
+Admin starts rollout from System Settings / System Images:
+
+1. Create a `runtime_rollouts` row.
+2. Update the runtime Deployment image/template.
+3. New version Pods register as ready.
+4. Old version Pods are marked `draining`.
+5. Draining Pods receive no new gateways.
+6. Scheduler migrates gateways in batches of 10.
+7. Each batch is health-checked.
+8. Failure pauses rollout.
+9. Admin can continue, pause, or roll back.
+10. Empty old Pods become `retired`.
+
+Deployment strategy:
+
+```text
+maxUnavailable: 0
+maxSurge: 1
+```
+
+ClawManager controls gateway migration instead of allowing Kubernetes rolling update to kill Pods that still host gateways.
+
+## Agent Contract
+
+Each runtime Pod runs one `clawmanager-agent`.
+
+Agent keeps existing active reporting abilities:
+
+```http
+POST /api/v1/agent/register
+POST /api/v1/agent/heartbeat
+POST /api/v1/agent/state/report
+POST /api/v1/agent/skills/inventory
+```
+
+Reporting expands from one instance to Pod plus many gateways:
+
+```json
+{
+ "agent_id": "openclaw-runtime-abc",
+ "runtime_type": "openclaw",
+ "pod_name": "openclaw-runtime-abc",
+ "pod_ip": "10.42.1.83",
+ "capacity": 100,
+ "used": 37,
+ "port_range": { "start": 20000, "end": 20099 },
+ "version": "openclaw:2.1.0",
+ "gateways": [
+ {
+ "instance_id": 42,
+ "port": 20017,
+ "pid": 812,
+ "status": "running",
+ "workspace_path": "/workspaces/openclaw/user-7/instance-42"
+ }
+ ]
+}
+```
+
+ClawManager actively calls agent on:
+
+```text
+http://:19090
+```
+
+All management calls use:
+
+```http
+Authorization: Bearer
+```
+
+Required agent management APIs:
+
+```http
+GET /healthz
+GET /capacity
+GET /gateways
+GET /gateways/{instance_id}
+POST /gateways
+POST /gateways/{instance_id}/stop
+POST /gateways/{instance_id}/restart
+POST /gateways/{instance_id}/recover
+DELETE /gateways/{instance_id}
+GET /gateways/{instance_id}/logs?tail=200
+```
+
+Create gateway request:
+
+```json
+{
+ "instance_id": 42,
+ "user_id": 7,
+ "agent_type": "openclaw",
+ "workspace_path": "/workspaces/openclaw/user-7/instance-42",
+ "port_range": { "start": 20000, "end": 20099 },
+ "env": {
+ "CLAWMANAGER_INSTANCE_ID": "42",
+ "CLAWMANAGER_LLM_BASE_URL": "http://clawmanager-gateway.clawmanager-system.svc.cluster.local:9001/api/v1/gateway/llm"
+ },
+ "resources": {
+ "cpu_cores": 0.5,
+ "memory_mb": 512,
+ "pids_limit": 256
+ }
+}
+```
+
+Create gateway response:
+
+```json
+{
+ "instance_id": 42,
+ "port": 20017,
+ "status": "running",
+ "pid": 812,
+ "url": "http://127.0.0.1:20017"
+}
+```
+
+Agent port requirements:
+
+- Pod-local gateway range is `20000-20099`.
+- Agent assigns the actual port.
+- Agent skips conflicts or returns structured errors.
+- Agent persists enough state to recover the port occupation map after restart.
+- Repeated `create` for the same instance is idempotent.
+
+Agent security requirements:
+
+- Each gateway runs as its own Linux user.
+- Deterministic identity:
+
+```text
+uid = 200000 + instance_id
+gid = 200000 + instance_id
+```
+
+- Agent creates uid/gid as needed.
+- Agent `chown`s workspace to that uid/gid.
+- Workspace permission should be `0700` or `0750`.
+- Gateway subprocess must not run as root.
+- Agent may run as root to manage users, ownership, and cgroups.
+- Agent must defend against `../`, absolute paths, and symlink escape.
+
+Agent resource requirements:
+
+- Each gateway uses a dedicated cgroup or systemd scope.
+- Enforce CPU quota, memory limit, and pids limit.
+- IO weight is outside the first release and can be added in a separate resource-control enhancement.
+- Agent reports cgroup OOM/limit failures.
+- Agent may restart failed gateways, then mark error after retry exhaustion.
+
+Agent health and recovery:
+
+- Check gateway health every 3 seconds.
+- Restart locally before reporting hard failure.
+- Support `recover` on a different Pod using the same workspace path.
+
+Agent metrics:
+
+- Pod-level CPU, memory, disk I/O, network in/out, used/capacity, workspace total.
+- Gateway-level instance_id, port, pid, status, CPU, memory, pids, network in/out, workspace_used_bytes, restart_count, last_error.
+
+## Proxying
+
+Frontend and iframe use:
+
+```text
+/api/v1/instances/{id}/proxy/
+```
+
+Backend checks user permission and active binding, then proxies to:
+
+```text
+http://{pod_ip}:{gateway_port}
+```
+
+HTTP and WebSocket traffic both use this path. The frontend path does not change after migration; only the binding changes.
+
+V2 does not create per-instance Kubernetes Services. It uses direct Pod IP plus gateway port.
+
+## Workspace File Management
+
+ClawManager backend directly reads and writes the shared workspace. File management is independent of the OpenClaw/Hermes iframe and works even when the instance is stopped.
+
+Supported operations:
+
+- List files and directories.
+- Text preview.
+- Image preview.
+- PDF preview.
+- Download.
+- Upload.
+- Create folder.
+- Rename file or directory.
+- Delete file or directory.
+
+API shape:
+
+```http
+GET /api/v1/instances/{id}/workspace/files?path=/
+GET /api/v1/instances/{id}/workspace/preview?path=/README.md
+GET /api/v1/instances/{id}/workspace/download?path=/README.md
+POST /api/v1/instances/{id}/workspace/upload
+POST /api/v1/instances/{id}/workspace/folders
+PATCH /api/v1/instances/{id}/workspace/rename
+DELETE /api/v1/instances/{id}/workspace/files
+```
+
+Preview support:
+
+- Text, maximum 1 MiB:
+ - `.txt`, `.md`, `.json`, `.yaml`, `.yml`, `.log`, `.py`, `.js`, `.ts`, `.go`, `.sh`
+- Images, maximum 10 MiB:
+ - `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`
+- PDF through browser iframe.
+- Other binary files are download-only.
+
+Upload defaults:
+
+- Maximum upload size: 500 MiB.
+- Configurable through environment variables.
+
+Security rules:
+
+1. API accepts relative paths only.
+2. Clean and join the user path with the instance workspace root.
+3. Resolve realpath.
+4. Final real path must remain inside the instance workspace root.
+5. Reject `../`.
+6. Reject absolute paths.
+7. Reject symlink escape.
+8. Upload filenames cannot contain path separators.
+9. Preview, download, delete, rename, and upload all use the same path guard.
+
+Workspace write operations use Redis path locks:
+
+```text
+lock:workspace:{instance_id}:{path_hash}
+```
+
+Logical disk quota:
+
+- `disk_gb` is the workspace quota.
+- Upload checks current size plus upload size before writing.
+- Agent periodically reports workspace usage.
+- If gateway writes beyond quota, agent reports `quota_exceeded`.
+- No filesystem project quota in the first version.
+
+Deletion:
+
+- No trash/recycle bin in V2 first version.
+- Deletes are direct and require confirmation.
+- Directory deletion displays item count before confirmation.
+
+Audit:
+
+- Audit all write operations: upload, delete, rename, create folder.
+- Audit download.
+- Do not audit preview.
+
+## Frontend Information Architecture
+
+Ordinary users only see usable product state.
+
+V2 also includes a UI simplification pass. The target style is quiet, direct, and work-focused:
+
+- Use a simple visual system with neutral backgrounds, restrained borders, clear spacing, and minimal decorative effects.
+- Avoid marketing-style hero areas, oversized titles, nested cards, ornamental gradients, and visual noise.
+- Prefer full-width sections and compact panels over many floating cards.
+- Use small, stable controls with clear labels and icons for common actions.
+- Keep ordinary user pages focused on the next useful action, not operational detail.
+- Keep admin pages denser and more table-oriented, with metrics designed for scanning and comparison.
+- Use consistent status language across pages: `Available`, `Starting`, `Unavailable` for users; `Ready`, `Draining`, `Unhealthy`, `Offline`, `Retired` for administrators.
+- Make responsive layouts predictable: iframe, file manager, tables, and toolbars must not overflow or overlap on mobile or desktop.
+
+User instance detail page shows:
+
+- Instance name.
+- Runtime type: OpenClaw or Hermes.
+- Availability: `Available`, `Starting`, `Unavailable`.
+- Start, Stop, Restart, Delete, Refresh, Fullscreen.
+- OpenClaw/Hermes iframe.
+- Workspace file manager.
+- Workspace usage.
+
+User page layout:
+
+```text
+[Compact title row: instance name, availability, primary actions]
+[OpenClaw/Hermes iframe with Refresh and Fullscreen]
+[Workspace file manager]
+```
+
+No separate service/resource/recent-status blocks appear on the ordinary user page. If an instance is unavailable, the page shows only actionable messages such as starting progress, retry start, or contact administrator.
+
+User instance detail page does not show:
+
+- Pod name or IP.
+- Gateway port.
+- Runtime capacity.
+- Runtime version.
+- Agent heartbeat.
+- Scheduler or migration details.
+- CPU, memory, network, disk runtime internals.
+- Service/resource/recent status operational cards.
+
+Admin adds a Runtime Pods page:
+
+- Runtime selector: OpenClaw / Hermes.
+- Pool summary: Pod count, gateway usage, CPU, memory, disk I/O, network.
+- Pod table: status, used/capacity, CPU, memory, disk I/O, network, version.
+- Selected Pod detail: Pod IP, agent heartbeat, port range, workspace mount, metrics chart.
+- Gateway distribution: instance, user, port, status.
+- Operations: Drain Pod, Resume Pod, Migrate Gateways, View Agent Logs, Scale Runtime Pool.
+
+Admin page style:
+
+- Use table-first layouts for Pods and gateways.
+- Use compact metric cells and sparklines rather than large decorative charts.
+- Keep dangerous operations grouped and confirm destructive or disruptive actions.
+- Do not hide operational detail from administrators, but keep it visually organized by pool, Pod, and gateway.
+
+Admin runtime data is pushed over WebSocket. Initial page load uses HTTP snapshot; updates use WebSocket from Redis-backed backend state. Agent reports metrics every 2 seconds.
+
+System Settings / System Images adds rollout controls:
+
+- OpenClaw runtime image.
+- Hermes runtime image.
+- Current version.
+- Target version.
+- Rollout status.
+- Old and new Pod counts.
+- Migrated and failed gateway counts.
+- Publish, pause, continue, rollback.
+
+## Legacy Compatibility
+
+V2 allows new instance creation only for:
+
+- `openclaw`
+- `hermes`
+
+Legacy types are not offered on the create page:
+
+- `ubuntu`
+- `debian`
+- `centos`
+- `custom`
+- `webtop`
+
+Existing legacy instances remain visible and are labeled `Legacy`. Their old detail and runtime behavior should remain available where practical. No automatic migration is performed. Admins can delete legacy instances. A legacy migration tool is out of scope for this V2 runtime-pool design.
+
+## Acceptance Criteria
+
+Instance creation:
+
+- Creating OpenClaw/Hermes does not create per-instance Pod/PVC/Service.
+- API returns `creating`.
+- Scheduler creates a gateway through agent.
+- Instance becomes `running`.
+- The 101st same-runtime instance scales the matching runtime Deployment.
+
+Port handling:
+
+- Gateway ports do not conflict within one Pod.
+- Agent restart restores port occupation state.
+- Binding records the actual assigned port.
+
+Access:
+
+- `/api/v1/instances/{id}/proxy/` opens OpenClaw/Hermes.
+- Frontend path remains unchanged after migration.
+- Ordinary users cannot see Pod/IP/port details.
+
+UI style:
+
+- Ordinary user pages use the simplified V2 style: compact title row, iframe, workspace file manager, and no runtime operational cards.
+- Admin pages use a simple operations-console style: dense tables, compact metrics, clear grouping, and no decorative dashboard chrome.
+- Text, buttons, toolbars, iframe, file manager, and runtime tables remain readable without overlap on mobile and desktop.
+- Status language is consistent with the V2 design vocabulary for user and admin contexts.
+
+Failover:
+
+- Runtime Pod deletion or restart migrates running instances within 5-10 seconds.
+- Workspace data remains intact.
+- Old orphan gateways are cleaned when old Pods return.
+
+Gray upgrade:
+
+- Publishing a new image starts new runtime Pods.
+- Old Pods enter draining.
+- Gateways migrate in batches.
+- Rollout can pause on failure.
+- Admin can continue or roll back.
+
+Workspace files:
+
+- Users can list, preview, download, upload, create folder, rename, and delete within their workspace.
+- Stopped instances still allow file operations.
+- Path escape and symlink escape are rejected.
+- Deletes require confirmation and do not use trash.
+- Write operations and downloads are audited.
+
+Admin runtime page:
+
+- Shows each runtime Pod status, gateway usage, CPU, memory, disk, and network.
+- Shows gateway distribution per Pod.
+- Supports drain, resume, migrate, log view, and scale operations.
+- Uses WebSocket for real-time updates.
+
+Deployment:
+
+- One YAML installs all required components.
+- Backend defaults to 3 replicas.
+- OpenClaw and Hermes runtime pools default to 1 replica each.
+- Redis, MySQL, and workspace-store are included and usable.
+
+## Open Risks
+
+- Default workspace-store is intentionally lightweight and not storage-layer HA.
+- Agent changes are on the critical path and must follow this contract.
+- Pod-level multi-tenancy requires careful Linux user, cgroup, and path isolation.
+- Rollout migration must be idempotent and pause safely on partial failures.
+- Metrics volume must be controlled through Redis aggregation and WebSocket subscriptions.
diff --git a/docs/superpowers/specs/2026-06-03-clawmanager-v2-e2e-design.md b/docs/superpowers/specs/2026-06-03-clawmanager-v2-e2e-design.md
new file mode 100644
index 0000000..18aa49f
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-03-clawmanager-v2-e2e-design.md
@@ -0,0 +1,472 @@
+# ClawManager V2 E2E Test Design
+
+## Overview
+
+ClawManager V2 needs an end-to-end test mechanism that covers user-facing flows across the React frontend, Go backend, MySQL migrations, and selected V2 runtime-pool APIs. The test suite should live in a root-level `e2e/` directory because it validates cross-service behavior rather than frontend-only behavior.
+
+The initial implementation should use Playwright. It fits the current Vite frontend plus Go backend setup, supports multiple local web servers, can persist authenticated browser state, and produces CI-friendly traces, screenshots, videos, and HTML reports.
+
+## Language And Tooling
+
+E2E test code should be written in TypeScript.
+
+- Test specs use Playwright Test with `.spec.ts` files.
+- Fixtures, page objects, setup files, API helpers, and environment helpers use `.ts`.
+- Optional command wrappers can use PowerShell (`.ps1`) and shell (`.sh`) so Windows and CI/Linux users have clear entry points.
+- JavaScript should not be used for hand-written e2e source files unless a tool generates it.
+
+TypeScript is the preferred language because the frontend already uses TypeScript, Playwright has strong TypeScript support, and typed fixtures/page objects reduce test maintenance risk as V2 flows grow.
+
+## Goals
+
+- Add a dedicated root-level `e2e/` test directory.
+- Support local developer execution with an isolated database.
+- Support CI execution with stable smoke tests.
+- Cover login, route protection, core user navigation, admin access control, workspace file flows, and V2 runtime-pool API surfaces.
+- Provide readable run logs, clear progress output, structured test results, and a final human-readable test report.
+- Integrate the P0 e2e suite into GitHub pull request checks.
+- Support manual local execution for P0, P1, P2, and the full suite.
+- Keep the first version independent of a real Kubernetes cluster or real runtime agent.
+- Leave room for a later full-stack k8s e2e mode that targets the existing kind smoke deployment.
+
+## Non-Goals
+
+- Do not replace backend Go unit or integration tests.
+- Do not move frontend tests into `e2e/`.
+- Do not require a real OpenClaw or Hermes runtime Pod for the initial suite.
+- Do not make heavy k8s browser tests block every pull request in the first iteration.
+
+## Recommended Directory Structure
+
+```text
+e2e/
+ package.json
+ package-lock.json
+ playwright.config.ts
+ README.md
+ .gitignore
+
+ docker/
+ docker-compose.e2e.yml
+
+ scripts/
+ reset-db.ts
+ wait-for.ts
+ run-with-log.ts
+ e2e-up.ps1
+ e2e-down.ps1
+ e2e-up.sh
+ e2e-down.sh
+
+ setup/
+ auth.setup.ts
+ db.setup.ts
+
+ fixtures/
+ test.ts
+ apiClient.ts
+ users.ts
+ env.ts
+
+ pages/
+ LoginPage.ts
+ DashboardPage.ts
+ InstanceListPage.ts
+ InstanceDetailPage.ts
+ AdminRuntimePodsPage.ts
+
+ tests/
+ smoke/
+ login.spec.ts
+ navigation.spec.ts
+ user/
+ dashboard.spec.ts
+ instances.spec.ts
+ workspace-files.spec.ts
+ admin/
+ runtime-pods.spec.ts
+ access-control.spec.ts
+ api/
+ auth.spec.ts
+ runtime-agent.spec.ts
+
+ reports/
+ .gitkeep
+```
+
+## Responsibilities
+
+`playwright.config.ts` defines browser projects, base URLs, reporters, traces, retries, timeouts, and the local web server orchestration.
+
+`docker/docker-compose.e2e.yml` starts only test dependencies that should be isolated from a developer machine, beginning with MySQL on a non-default host port such as `13307`.
+
+`scripts/` contains explicit helper commands for resetting the e2e database, waiting for ports or health endpoints, and starting or stopping local dependencies on Windows and Unix-like systems.
+
+`scripts/run-with-log.ts` wraps Playwright execution when needed so console output is also written to `e2e/reports/run.log`.
+
+`setup/` contains Playwright project dependencies. `db.setup.ts` prepares deterministic data. `auth.setup.ts` logs in as seeded users and writes browser storage state files for later specs.
+
+`fixtures/` contains typed shared utilities: environment parsing, API request helpers, seeded user constants, and a custom Playwright `test` export.
+
+`pages/` contains page objects for stable selectors and common user actions. Page objects should stay small and focused on navigation and interactions, not assertions-heavy business logic.
+
+`tests/` groups specs by product surface rather than by technical layer. Smoke tests are intentionally tiny and run first in CI.
+
+`reports/` stores generated run logs and machine-readable report files. Generated report artifacts are ignored by git except for a `.gitkeep` tracked marker.
+
+## Reuse And Common Module Guidelines
+
+E2E implementation must prefer shared modules over repeated setup code. Repeated steps are expected across login, role switching, API calls, database setup, runtime pod seeding, navigation, and reporting, so the first implementation batch must establish reusable foundations before adding many specs.
+
+Required shared modules:
+
+- `fixtures/test.ts` exports the shared Playwright `test` and `expect`, wires common fixtures, and centralizes base URL, storage state, and artifact behavior.
+- `fixtures/env.ts` owns environment parsing for frontend URL, backend URL, database connection, runtime agent token, workspace root, and CI flags.
+- `fixtures/apiClient.ts` owns typed request helpers for auth, runtime-agent, admin runtime Pods, and authenticated API calls.
+- `fixtures/users.ts` owns seeded user constants such as `admin/admin123` and any generated non-admin test user data.
+- `setup/auth.setup.ts` performs reusable login setup and writes storage state files instead of logging in manually in every UI spec.
+- `setup/db.setup.ts` prepares deterministic database and workspace state for specs that need seeded V2 runtime data.
+- `pages/*.ts` page objects encapsulate repeated UI actions and selectors. Tests should describe user intent; page objects should hold selector details.
+- `scripts/*.ts` own lifecycle concerns such as database reset, server readiness, process orchestration, logging, and report paths.
+
+Reuse rules:
+
+- Do not duplicate login steps inside every spec when a storage state fixture can be used.
+- Do not hard-code backend or frontend URLs inside specs; read them from `fixtures/env.ts`.
+- Do not repeat raw runtime-agent request construction in multiple tests; use `apiClient.ts`.
+- Do not repeat selectors across specs; move repeated selectors and actions into page objects.
+- Do not add test-only helpers to production frontend or backend code for e2e convenience.
+- Keep page objects small: one page object should cover one page or stable product surface.
+- Keep shared helpers behavior-focused. Avoid large catch-all utility files.
+- When a repeated sequence appears in two specs, extract it before adding a third copy.
+
+## Runtime Model
+
+The initial local flow should start:
+
+1. MySQL through `e2e/docker/docker-compose.e2e.yml`.
+2. Go backend from `backend/cmd/server`, with environment overrides:
+ - `SERVER_ADDRESS=:9001`
+ - `DB_HOST=127.0.0.1`
+ - `DB_PORT=13307`
+ - `DB_USER=root`
+ - `DB_PASSWORD=123456`
+ - `DB_NAME=clawmanager_e2e`
+ - `JWT_SECRET=clawmanager-e2e-secret`
+ - `RUNTIME_SCHEDULER_ENABLED=false`
+ - `RUNTIME_WORKSPACE_ROOT=/.cache/e2e/workspaces`
+ - `OBJECT_STORAGE_LOCAL_FALLBACK=/.cache/e2e/object-storage`
+ - `SKILL_SCANNER_ENABLED=false`
+3. Vite frontend from `frontend`, using the existing `9002` dev port and `/api` proxy to backend `9001`.
+4. Playwright tests against `http://127.0.0.1:9002`.
+
+The backend already applies embedded migrations during startup, so e2e does not need a separate migration runner. Database reset can drop and recreate `clawmanager_e2e` before backend startup.
+
+## Run Logging, Progress, And Reports
+
+E2E execution must make progress and results easy to inspect during and after a run.
+
+Console progress:
+
+- Use Playwright's list-style console reporter for local runs so each test is visible as it starts and finishes.
+- Test titles should include the priority tag, such as `@p0`, `@p1`, or `@p2`.
+- Long tests should use `test.step(...)` for meaningful milestones such as login, seed data creation, navigation, API call, and assertion phases.
+- Setup scripts should print clear lifecycle messages for database reset, backend startup, frontend startup, auth setup, and report location.
+
+Run log:
+
+- Every standard script should write a timestamped log to `e2e/reports/run.log`.
+- CI should also retain raw job logs, but `run.log` is the repository-level e2e artifact.
+- Logs must not print access tokens, refresh tokens, passwords, or full authorization headers.
+- On failure, logs should include the failing test name, retry count, browser project, and the Playwright artifact path.
+
+Report artifacts:
+
+- Human-readable HTML report: `e2e/playwright-report/`.
+- Raw per-test artifacts: `e2e/test-results/`.
+- Machine-readable JSON report: `e2e/reports/results.json`.
+- CI-friendly JUnit report: `e2e/reports/junit.xml`.
+- Text run log: `e2e/reports/run.log`.
+
+Recommended package scripts:
+
+```json
+{
+ "scripts": {
+ "test:p0": "playwright test --grep @p0",
+ "test:p1": "playwright test --grep @p1",
+ "test:p2": "playwright test --grep @p2",
+ "test:all": "playwright test",
+ "ci:p0": "playwright test --grep @p0 --workers=1",
+ "test:report": "playwright show-report playwright-report"
+ }
+}
+```
+
+`playwright.config.ts` should configure at least these reporters:
+
+- `list` for clear live progress.
+- `html` for the final local/CI report.
+- `json` written to `e2e/reports/results.json`.
+- `junit` written to `e2e/reports/junit.xml`.
+
+CI must upload `e2e/playwright-report/`, `e2e/test-results/`, and `e2e/reports/` whenever e2e runs fail. Local users can open the final report with `npm run test:report`.
+
+## Test Data Strategy
+
+Use seeded migration data where it is stable. The default admin account is:
+
+```text
+username: admin
+password: admin123
+```
+
+Additional test data should be created through APIs when possible. For flows that require a specific V2 state not naturally reachable without k8s, `db.setup.ts` may insert deterministic rows directly after migrations have run. Direct database setup is acceptable for initial e2e because the target behavior is browser and API behavior, not migration correctness.
+
+Each spec should use unique names with a run prefix when it creates mutable data. Cleanup should happen through API calls where practical, with database reset reserved for suite setup.
+
+## Test Case Inventory And Priority
+
+The suite should be planned from a full test inventory, then implemented in priority batches. Each batch must be developed, run, fixed, and reviewed before starting the next batch. P0 is the first implementation batch and acts as the required core gate.
+
+### P0: Core Gate
+
+P0 proves the product can boot, authenticate, protect routes, and expose the most critical V2 surfaces without requiring a real k8s cluster or runtime agent.
+
+- `smoke/login.spec.ts`
+ - Login page renders.
+ - Admin can log in with `admin/admin123`.
+ - Login failure shows a user-visible error and stays on `/login`.
+- `smoke/navigation.spec.ts`
+ - Unauthenticated users are redirected to `/login`.
+ - Authenticated admin reaches `/dashboard`.
+ - Main authenticated navigation can reach instances and settings/admin entry points that are visible for the logged-in role.
+- `admin/access-control.spec.ts`
+ - Non-admin users cannot open admin routes.
+ - Admin users can open the admin runtime Pods route.
+- `api/auth.spec.ts`
+ - `/api/v1/auth/login` returns access and refresh tokens.
+ - `/api/v1/auth/me` returns the current user when called with a valid token.
+ - `/api/v1/auth/me` rejects unauthenticated requests.
+- `api/runtime-agent.spec.ts`
+ - Runtime-agent register persists an `openclaw` runtime pod.
+ - Runtime-agent heartbeat updates pod health state.
+ - Invalid runtime-agent payloads are rejected with a non-2xx response.
+- `admin/runtime-pods.spec.ts`
+ - Admin runtime Pods page renders an empty state.
+ - Admin runtime Pods page renders a seeded pod row with status and capacity fields.
+
+P0 completion criteria:
+
+- P0 passes locally on Chromium.
+- P0 passes in CI with one worker.
+- Console progress, `e2e/reports/run.log`, HTML report, JSON report, JUnit report, traces, and screenshots are produced as configured.
+- Playwright trace, report, and log artifacts are uploaded on CI failure.
+- No P1 or P2 tests are required for the first e2e gate.
+
+### P1: V2 User Workflows
+
+P1 covers the main user paths most likely to catch frontend/backend integration regressions after P0 is stable.
+
+- `user/dashboard.spec.ts`
+ - Dashboard loads quota and instance summary.
+ - Dashboard handles zero instances.
+ - Dashboard links to create instance and instance list.
+- `user/instances.spec.ts`
+ - Instance list handles empty state.
+ - Instance list renders seeded V2 `openclaw` and `hermes` instances.
+ - Instance detail shows the simplified V2 layout for a seeded V2 instance.
+ - Instance detail shows actionable unavailable state for a stopped or creating instance.
+- `user/workspace-files.spec.ts`
+ - Workspace file manager lists the seeded workspace root.
+ - User can create a folder.
+ - User can upload a small text file.
+ - User can preview the uploaded file.
+ - User can download the uploaded file.
+ - User can rename a file or folder.
+ - User can delete a file or folder.
+ - Path traversal attempts are rejected through the UI/API path.
+- `api/runtime-agent.spec.ts`
+ - Runtime-agent metrics report updates pod CPU, memory, disk, and network fields.
+ - Runtime-agent gateways report updates gateway rows for admin runtime view.
+
+P1 completion criteria:
+
+- P0 and P1 pass locally.
+- P0 remains the required PR gate.
+- P1 produces the same log and report artifacts as P0.
+- P1 can run in CI as required or manual depending on runtime and database timing stability.
+
+### P2: Expanded Operations And Full-Stack Confidence
+
+P2 validates broader operational flows and should be introduced only after P0 and P1 are reliable.
+
+- `admin/runtime-pods.spec.ts`
+ - Admin runtime Pods page renders seeded gateway rows.
+ - Runtime pod drain action calls the expected API and reflects the response.
+ - Runtime rollout action can be submitted with a test image and shows rollout feedback.
+- `user/instances.spec.ts`
+ - Create instance form validates required fields.
+ - Create instance submits a minimal V2 instance request.
+ - Start, stop, restart, and sync actions show expected UI transitions for seeded or mocked backend state.
+- `admin/access-control.spec.ts`
+ - User-scoped instance list excludes another user's seeded instances.
+ - Admin instance list includes cross-user seeded instances.
+- `k8s/smoke.spec.ts`
+ - Browser can load the app through `https://127.0.0.1:8443` after kind deployment.
+ - Admin can log in through the deployed nginx endpoint.
+ - Health page and frontend route fallback work through the deployed endpoint.
+
+P2 completion criteria:
+
+- P0 and P1 remain stable.
+- P2 can run manually or on a schedule.
+- P2 produces the same log and report artifacts as P0.
+- k8s browser tests are not required for every pull request until deployment timing and runtime image availability are proven stable.
+
+## Local Manual Runs
+
+Developers must be able to run e2e locally without GitHub.
+
+First-time setup:
+
+```bash
+cd e2e
+npm ci
+npx playwright install chromium
+```
+
+Standard local commands:
+
+```bash
+cd e2e
+npm run test:p0
+npm run test:p1
+npm run test:p2
+npm run test:all
+npm run test:report
+```
+
+Windows helpers should provide equivalent entry points:
+
+```powershell
+.\scripts\e2e-up.ps1
+npm run test:p0
+npm run test:report
+.\scripts\e2e-down.ps1
+```
+
+Unix-like helpers should provide equivalent entry points:
+
+```bash
+./scripts/e2e-up.sh
+npm run test:p0
+npm run test:report
+./scripts/e2e-down.sh
+```
+
+Local runs should produce the same log and report outputs as CI. The local default is P0. P1, P2, and `test:all` are explicit commands so longer tests are intentional.
+
+## GitHub Actions Integration
+
+Add an e2e PR check to GitHub Actions. The recommended implementation is to add an `e2e-p0` job to the existing `.github/workflows/build.yml` workflow so it appears alongside the existing frontend, backend, Docker, and k8s smoke checks on pull requests.
+
+The PR check requirements are:
+
+- Trigger on `pull_request`.
+- Also run on pushes to the same protected branch patterns as the existing build workflow.
+- Depend on successful `frontend` and `backend` jobs.
+- Run only the P0 suite initially.
+- Use Chromium with one worker for stability.
+- Upload logs and reports on failure.
+- Fail the PR check when P0 fails.
+
+The first GitHub PR command should be:
+
+Recommended CI commands:
+
+```bash
+cd e2e
+npm ci
+npx playwright install --with-deps chromium
+npm run ci:p0
+```
+
+P1 can be added to CI after it is stable locally. P2 should begin as manual or scheduled CI. The e2e job should not run the full k8s browser suite initially. A later workflow can reuse the existing kind deployment smoke path and then run a small Playwright suite against `https://127.0.0.1:8443`.
+
+GitHub manual runs should also be supported. The existing build workflow can add `workflow_dispatch` with an `e2e_suite` input:
+
+```text
+p0 | p1 | p2 | all
+```
+
+The manual run should map the input to:
+
+- `p0`: `npm run ci:p0`
+- `p1`: `npm run test:p1 -- --workers=1`
+- `p2`: `npm run test:p2 -- --workers=1`
+- `all`: `npm run test:all -- --workers=1`
+
+Artifact upload must include:
+
+- `e2e/playwright-report/`
+- `e2e/test-results/`
+- `e2e/reports/run.log`
+- `e2e/reports/results.json`
+- `e2e/reports/junit.xml`
+
+The GitHub summary should include the suite name, pass/fail status, total test count, failed test names, and a pointer to the uploaded HTML report artifact.
+
+## Phased Implementation
+
+Implementation must proceed batch by batch. A later batch should not start until the current batch is implemented, verified, and reviewed.
+
+Batch 0 prepares the harness:
+
+- Create the root `e2e/` package.
+- Add Playwright config, isolated MySQL compose file, setup projects, fixtures, scripts, and README.
+- Add local manual run commands and helper scripts.
+- Add GitHub artifact wiring for logs and reports.
+- Verify that the empty harness can start MySQL, backend, frontend, and one minimal smoke test.
+
+Batch 1 implements P0:
+
+- Add P0 smoke, auth API, access-control, runtime-agent, and admin runtime Pods tests.
+- Add an `e2e-p0` GitHub Actions PR check to the existing build workflow.
+- Make `npm run ci:p0` the first GitHub PR e2e command.
+- Fix selectors, setup data, and server orchestration until P0 passes locally and in CI.
+- Stop after P0 and review results before adding P1.
+
+Batch 2 implements P1:
+
+- Add dashboard, instance list/detail, workspace file, and runtime metrics/gateway reporting tests.
+- Add any deterministic V2 seed helpers required by those specs.
+- Keep P0 as the required PR gate until P1 has passed repeatedly.
+- Review P1 stability before making it required in CI.
+
+Batch 3 implements P2:
+
+- Add expanded admin operations, instance action, cross-user visibility, and k8s deployed smoke tests.
+- Keep k8s browser tests manual or scheduled first.
+- Promote P2 subsets into PR CI only after timing and runtime image stability are proven.
+
+## Acceptance Criteria
+
+- `e2e/` exists at the repository root and owns all browser e2e test assets.
+- Developers can run the suite without modifying local frontend or backend configuration files.
+- Developers can manually run P0, P1, P2, or all e2e tests locally from `e2e/`.
+- The suite uses an isolated database and workspace cache path.
+- GitHub Actions runs the P0 e2e suite as a pull request check.
+- GitHub Actions can also run e2e manually through `workflow_dispatch`.
+- CI can run the P0 suite and upload failure artifacts.
+- E2E source files are written in TypeScript.
+- E2E runs show readable live progress in the terminal.
+- E2E runs generate `e2e/reports/run.log`.
+- E2E runs generate a final HTML report in `e2e/playwright-report/`.
+- E2E runs generate JSON and JUnit result files for CI consumption.
+- Repeated login, API, setup, navigation, and runtime-agent operations are implemented through shared fixtures, helpers, setup files, or page objects.
+- Specs do not duplicate URLs, credentials, selectors, or raw runtime-agent payload construction when a shared module exists.
+- Tests are grouped by product surface, assigned P0/P1/P2 priority, and can be expanded without changing the directory model.
+- The full necessary test inventory is documented before implementation begins.
+- Each implementation batch is verified before the next batch starts.
+- Initial tests do not require a real k8s cluster or runtime agent.
diff --git a/e2e/.gitignore b/e2e/.gitignore
new file mode 100644
index 0000000..e403392
--- /dev/null
+++ b/e2e/.gitignore
@@ -0,0 +1,7 @@
+node_modules/
+playwright-report/
+test-results/
+reports/*
+!reports/.gitkeep
+.auth/
+.cache/
diff --git a/e2e/README.md b/e2e/README.md
new file mode 100644
index 0000000..31709c6
--- /dev/null
+++ b/e2e/README.md
@@ -0,0 +1,47 @@
+# ClawManager E2E
+
+This directory contains Playwright-based TypeScript e2e tests.
+
+## First-Time Setup
+
+```bash
+npm ci
+npx playwright install chromium
+```
+
+## Run Locally
+
+```bash
+npm run test:p0
+npm run test:report
+```
+
+The default local gate is P0. P1, P2, and all tests are explicit:
+
+```bash
+npm run test:p1
+npm run test:p2
+npm run test:all
+```
+
+## Run Against A Target Environment
+
+Pass only the ClawManager address. The runner defaults to the P0 suite, derives
+the backend API as `/api/v1`, runs serially, skips local-only data setup, and
+writes a dedicated target log.
+
+```bash
+npm run target -- 172.16.1.12:39443
+```
+
+The address may include a protocol. When omitted, `https://` is used.
+
+## Reports
+
+- Live progress appears in the terminal.
+- Local run log: `reports/run.log`
+- Target run log: `reports/target-run.log`
+- JSON: `reports/results.json`
+- JUnit: `reports/junit.xml`
+- HTML: `playwright-report/`
+- Raw artifacts: `test-results/`
diff --git a/e2e/docker/docker-compose.e2e.yml b/e2e/docker/docker-compose.e2e.yml
new file mode 100644
index 0000000..117e7c1
--- /dev/null
+++ b/e2e/docker/docker-compose.e2e.yml
@@ -0,0 +1,16 @@
+services:
+ mysql:
+ image: mysql:8.0
+ container_name: clawmanager-e2e-mysql
+ environment:
+ MYSQL_ROOT_PASSWORD: "123456"
+ MYSQL_DATABASE: "clawmanager_e2e"
+ ports:
+ - "13307:3306"
+ command: --default-authentication-plugin=mysql_native_password
+ healthcheck:
+ test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uroot", "-p123456"]
+ interval: 5s
+ timeout: 5s
+ retries: 20
+
diff --git a/e2e/docs/lite-pro-feature-matrix.md b/e2e/docs/lite-pro-feature-matrix.md
new file mode 100644
index 0000000..038cc75
--- /dev/null
+++ b/e2e/docs/lite-pro-feature-matrix.md
@@ -0,0 +1,14 @@
+# Lite / Pro Feature Matrix
+
+This matrix is the source checklist for the Playwright coverage in
+`tests/instances/lite-pro-modes.spec.ts`.
+
+| Area | Lite | Pro | E2E coverage |
+| --- | --- | --- | --- |
+| Create wizard | Selectable `Lite` mode. Runtime backend is derived as `Gateway`. | Selectable `Pro` mode. Runtime backend is derived as `Desktop`. | `create wizard exposes the lite/pro mode contract` |
+| Resource selection | Does not require or show dedicated CPU, memory, storage, or GPU sizing. Dedicated resource quota checks are not applied. | Shows dedicated resource presets and GPU toggle. CPU, memory, storage, and GPU quota checks are applied. | `create wizard exposes the lite/pro mode contract` |
+| Runtime ownership | Uses the shared gateway runtime pool and keeps gateway-level identity separate. | Uses a dedicated desktop runtime backed by Kubernetes Deployment + Service. | `admin instances page surfaces mode and backend management controls` |
+| Detail layout | Shows the service frame and workspace manager without desktop-only management panels. | Shows the service frame plus a merged Runtime Overview card, Runtime Events, Instance Skills, and workspace manager rooted at `/config`. | `lite detail keeps gateway workspace layout`, `pro detail keeps desktop management layout` |
+| Channel / skill management | Supports OpenClaw injection, channel selection, skill injection, import, and export at create/manage time. | Supports OpenClaw injection, channel selection, skill injection, import, export, and instance skill attach/remove. | Create wizard assertions plus pro detail skill panel assertion |
+| External access | Supports short Share Link and Password access with fixed, custom, or permanent expiration. | Supports short Share Link and Password access with fixed, custom, or permanent expiration. | `password share link opens a password gate` |
+| Admin monitoring | Admin instance management can show/filter Lite records and identify them as `Gateway binding` / `Gateway`. | Admin instance management can show/filter Pro records and identify them as `Deployment` / `Desktop`. | `admin instances page surfaces mode and backend management controls` |
diff --git a/e2e/fixtures/apiClient.ts b/e2e/fixtures/apiClient.ts
new file mode 100644
index 0000000..f2e11cc
--- /dev/null
+++ b/e2e/fixtures/apiClient.ts
@@ -0,0 +1,398 @@
+import type { APIRequestContext, APIResponse } from "@playwright/test";
+import { env } from "./env.js";
+import { users } from "./users.js";
+
+interface ApiEnvelope {
+ success: boolean;
+ message?: string;
+ data: T;
+ error?: string;
+}
+
+export interface LoginTokens {
+ access_token: string;
+ refresh_token: string;
+ expires_in: number;
+}
+
+export interface CurrentUser {
+ id: number;
+ username: string;
+ email: string;
+ role: string;
+}
+
+export interface RuntimePod {
+ id: number;
+ runtime_type: "openclaw" | "hermes";
+ namespace: string;
+ pod_name: string;
+ pod_uid?: string;
+ pod_ip?: string;
+ node_name?: string;
+ deployment_name: string;
+ image_ref: string;
+ state: string;
+ capacity: number;
+ used_slots: number;
+ draining: boolean;
+}
+
+export interface InstanceRecord {
+ id: number;
+ user_id: number;
+ name: string;
+ type: string;
+ runtime_type: "desktop" | "shell" | "gateway" | string;
+ instance_mode?: "lite" | "pro" | string;
+ status: "creating" | "running" | "stopped" | "error" | "deleting" | string;
+ cpu_cores: number;
+ memory_gb: number;
+ disk_gb: number;
+ gpu_enabled: boolean;
+ gpu_count: number;
+ os_type?: string;
+ os_version?: string;
+ pod_name?: string;
+ pod_namespace?: string;
+ pod_ip?: string;
+ workspace_usage_bytes?: number;
+ created_at?: string;
+ updated_at?: string;
+}
+
+export interface InstanceListResponse {
+ instances: InstanceRecord[];
+ total: number;
+ page: number;
+ limit: number;
+}
+
+export interface TeamRecord {
+ id: number;
+ user_id: number;
+ name: string;
+ description?: string;
+ status: "creating" | "running" | "failed" | "deleting" | "deleted" | string;
+ communication_mode: string;
+ shared_mount_path: string;
+ created_at?: string;
+ updated_at?: string;
+}
+
+export interface TeamMemberRecord {
+ id: number;
+ team_id: number;
+ instance_id?: number;
+ user_id: number;
+ member_key: string;
+ display_name: string;
+ role: string;
+ runtime_type?: "openclaw" | "hermes" | string;
+ instance_mode?: "lite" | "pro" | string;
+ status: "creating" | "idle" | "busy" | "failed" | "offline" | "deleting" | "deleted" | string;
+}
+
+export interface TeamDetailsRecord {
+ team: TeamRecord;
+ leader_member_id?: string;
+ leader?: TeamMemberRecord;
+ members: TeamMemberRecord[];
+}
+
+export interface CreateTeamMemberRequest {
+ member_id?: string;
+ name?: string;
+ role: string;
+ mode?: "lite" | "pro";
+ instance_mode?: "lite" | "pro";
+ runtime_type?: "openclaw" | "hermes";
+ description?: string;
+ cpu_cores?: number;
+ memory_gb?: number;
+ disk_gb?: number;
+ gpu_enabled?: boolean;
+ gpu_count?: number;
+ is_leader?: boolean;
+}
+
+export interface CreateTeamRequest {
+ name: string;
+ description?: string;
+ communication_mode?: string;
+ shared_storage_gb?: number;
+ members: CreateTeamMemberRequest[];
+}
+
+export interface InstanceExternalAccess {
+ id: number;
+ instance_id: number;
+ enabled: boolean;
+ auth_mode: "share_link" | "password" | string;
+ password_hint?: string;
+ expires_at?: string;
+ created_by?: number;
+ last_used_at?: string;
+ created_at: string;
+ updated_at: string;
+}
+
+export interface ExternalAccessRequest {
+ expires_mode?: "preset" | "custom" | "permanent";
+ expires_preset?: "1h" | "24h" | "7d" | "30d";
+ expires_at?: string;
+}
+
+export interface PasswordExternalAccessResult {
+ access: InstanceExternalAccess;
+ password: string;
+ share_url?: string;
+}
+
+export interface RuntimePodRegisterRequest {
+ runtime_type: "openclaw" | "hermes" | string;
+ namespace: string;
+ pod_name: string;
+ pod_uid?: string;
+ pod_ip?: string;
+ node_name?: string;
+ deployment_name: string;
+ image_ref: string;
+ agent_endpoint?: string;
+ state: string;
+ capacity: number;
+ used_slots: number;
+ draining: boolean;
+}
+
+export interface RuntimePodIdentity {
+ pod_id?: number;
+ namespace?: string;
+ pod_name?: string;
+}
+
+export interface RuntimeHeartbeatRequest extends RuntimePodIdentity {
+ state: string;
+ used_slots: number;
+ draining: boolean;
+}
+
+export interface LoginUser {
+ username: string;
+ password: string;
+}
+
+export interface RegisterUser extends LoginUser {
+ email: string;
+}
+
+export const defaultRuntimePod: RuntimePodRegisterRequest = {
+ runtime_type: "openclaw",
+ namespace: "clawmanager-e2e",
+ pod_name: "e2e-openclaw-runtime-p0",
+ pod_uid: "e2e-openclaw-runtime-p0-uid",
+ pod_ip: "10.244.0.25",
+ node_name: "e2e-node",
+ deployment_name: "openclaw-runtime",
+ image_ref: "e2e/openclaw:latest",
+ agent_endpoint: "http://10.244.0.25:18080",
+ state: "ready",
+ capacity: 100,
+ used_slots: 0,
+ draining: false
+};
+
+function bearer(accessToken: string) {
+ return { Authorization: `Bearer ${accessToken}` };
+}
+
+function runtimeAgentHeaders() {
+ return { "X-ClawManager-Agent-Token": env.runtimeAgentToken };
+}
+
+async function parseJson(response: APIResponse): Promise {
+ const text = await response.text();
+ if (!text) {
+ return undefined as T;
+ }
+ return JSON.parse(text) as T;
+}
+
+async function expectOkEnvelope(response: APIResponse): Promise {
+ const payload = await parseJson>(response);
+ if (!response.ok() || !payload.success) {
+ throw new Error(payload?.error || `request failed with status ${response.status()}`);
+ }
+ return payload.data;
+}
+
+export async function login(
+ request: APIRequestContext,
+ user: LoginUser = users.admin
+): Promise {
+ const response = await request.post(`${env.backendUrl}/auth/login`, {
+ data: {
+ username: user.username,
+ password: user.password
+ }
+ });
+ return expectOkEnvelope(response);
+}
+
+export async function registerUser(
+ request: APIRequestContext,
+ user: RegisterUser = users.user
+): Promise {
+ const response = await request.post(`${env.backendUrl}/auth/register`, {
+ data: {
+ username: user.username,
+ email: user.email,
+ password: user.password
+ }
+ });
+ await expectOkEnvelope(response);
+}
+
+export async function getMe(
+ request: APIRequestContext,
+ accessToken: string
+): Promise {
+ const response = await request.get(`${env.backendUrl}/auth/me`, {
+ headers: bearer(accessToken)
+ });
+ return expectOkEnvelope(response);
+}
+
+export async function getMeRaw(
+ request: APIRequestContext,
+ accessToken?: string
+): Promise {
+ return request.get(`${env.backendUrl}/auth/me`, {
+ headers: accessToken ? bearer(accessToken) : undefined
+ });
+}
+
+export async function postRuntimePodRegisterRaw(
+ request: APIRequestContext,
+ overrides: Partial = {}
+): Promise {
+ return request.post(`${env.backendUrl}/runtime-agent/register`, {
+ headers: runtimeAgentHeaders(),
+ data: {
+ ...defaultRuntimePod,
+ ...overrides
+ }
+ });
+}
+
+export async function registerRuntimePod(
+ request: APIRequestContext,
+ overrides: Partial = {}
+): Promise {
+ const response = await postRuntimePodRegisterRaw(request, overrides);
+ const data = await expectOkEnvelope<{ pod: RuntimePod }>(response);
+ return data.pod;
+}
+
+export async function sendRuntimeHeartbeat(
+ request: APIRequestContext,
+ identity: RuntimePodIdentity,
+ overrides: Partial = {}
+): Promise {
+ const response = await request.post(`${env.backendUrl}/runtime-agent/heartbeat`, {
+ headers: runtimeAgentHeaders(),
+ data: {
+ state: "ready",
+ used_slots: 0,
+ draining: false,
+ ...identity,
+ ...overrides
+ }
+ });
+ await expectOkEnvelope(response);
+}
+
+export async function listRuntimePods(
+ request: APIRequestContext,
+ accessToken: string
+): Promise {
+ const response = await request.get(`${env.backendUrl}/admin/runtime-pods`, {
+ headers: bearer(accessToken)
+ });
+ const data = await expectOkEnvelope<{ pods: RuntimePod[] }>(response);
+ return data.pods;
+}
+
+export async function listInstances(
+ request: APIRequestContext,
+ accessToken: string,
+ options: { admin?: boolean; page?: number; limit?: number } = {}
+): Promise {
+ const endpoint = options.admin ? "/admin/instances" : "/instances";
+ const response = await request.get(`${env.backendUrl}${endpoint}`, {
+ headers: bearer(accessToken),
+ params: {
+ page: options.page ?? 1,
+ limit: options.limit ?? 100
+ }
+ });
+ return expectOkEnvelope(response);
+}
+
+export async function createTeam(
+ request: APIRequestContext,
+ accessToken: string,
+ data: CreateTeamRequest
+): Promise {
+ const response = await request.post(`${env.backendUrl}/teams`, {
+ headers: bearer(accessToken),
+ data
+ });
+ return expectOkEnvelope(response);
+}
+
+export async function getTeam(
+ request: APIRequestContext,
+ accessToken: string,
+ teamId: number
+): Promise {
+ const response = await request.get(`${env.backendUrl}/teams/${teamId}`, {
+ headers: bearer(accessToken)
+ });
+ return expectOkEnvelope(response);
+}
+
+export async function deleteTeam(
+ request: APIRequestContext,
+ accessToken: string,
+ teamId: number
+): Promise {
+ const response = await request.delete(`${env.backendUrl}/teams/${teamId}`, {
+ headers: bearer(accessToken)
+ });
+ await expectOkEnvelope<{ id: number }>(response);
+}
+
+export async function createExternalAccessPassword(
+ request: APIRequestContext,
+ accessToken: string,
+ instanceId: number,
+ data: ExternalAccessRequest = { expires_mode: "preset", expires_preset: "1h" }
+): Promise {
+ const response = await request.post(`${env.backendUrl}/instances/${instanceId}/external-access/password`, {
+ headers: bearer(accessToken),
+ data
+ });
+ return expectOkEnvelope(response);
+}
+
+export async function disableExternalAccess(
+ request: APIRequestContext,
+ accessToken: string,
+ instanceId: number
+): Promise {
+ const response = await request.delete(`${env.backendUrl}/instances/${instanceId}/external-access`, {
+ headers: bearer(accessToken)
+ });
+ await expectOkEnvelope(response);
+}
diff --git a/e2e/fixtures/env.ts b/e2e/fixtures/env.ts
new file mode 100644
index 0000000..28eb8e4
--- /dev/null
+++ b/e2e/fixtures/env.ts
@@ -0,0 +1,64 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const fixturesDir = path.dirname(fileURLToPath(import.meta.url));
+export const e2eRoot = path.resolve(fixturesDir, "..");
+export const repoRoot = path.resolve(e2eRoot, "..");
+export const reportsDir = path.join(e2eRoot, "reports");
+export const testResultsDir = path.join(e2eRoot, "test-results");
+
+function readEnv(name: string, fallback: string): string {
+ const value = process.env[name]?.trim();
+ return value && value.length > 0 ? value : fallback;
+}
+
+function readNumberEnv(name: string, fallback: number): number {
+ const raw = process.env[name]?.trim();
+ if (!raw) {
+ return fallback;
+ }
+ const parsed = Number.parseInt(raw, 10);
+ if (!Number.isFinite(parsed)) {
+ throw new Error(`${name} must be a number`);
+ }
+ return parsed;
+}
+
+function readBooleanEnv(name: string, fallback: boolean): boolean {
+ const raw = process.env[name]?.trim();
+ if (!raw) {
+ return fallback;
+ }
+ return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+
+function withoutTrailingSlash(value: string): string {
+ return value.replace(/\/+$/, "");
+}
+
+const isCI = process.env.CI === "true" || process.env.E2E_CI === "true";
+const debug = readBooleanEnv("E2E_DEBUG", false);
+
+export const env = {
+ frontendUrl: withoutTrailingSlash(readEnv("E2E_FRONTEND_URL", "http://127.0.0.1:9002")),
+ backendUrl: withoutTrailingSlash(readEnv("E2E_BACKEND_URL", "http://127.0.0.1:9001/api/v1")),
+ db: {
+ host: readEnv("E2E_DB_HOST", "127.0.0.1"),
+ port: readNumberEnv("E2E_DB_PORT", 13307),
+ user: readEnv("E2E_DB_USER", "root"),
+ password: readEnv("E2E_DB_PASSWORD", "123456"),
+ database: readEnv("E2E_DB_NAME", "clawmanager_e2e")
+ },
+ runtimeAgentToken: readEnv("E2E_RUNTIME_AGENT_TOKEN", "e2e-runtime-agent-token"),
+ workspaceRoot: readEnv("E2E_WORKSPACE_ROOT", path.join(repoRoot, ".cache", "e2e", "workspaces")),
+ objectStorageFallback: readEnv(
+ "E2E_OBJECT_STORAGE_FALLBACK",
+ path.join(repoRoot, ".cache", "e2e", "object-storage")
+ ),
+ ignoreHttpsErrors: readBooleanEnv("E2E_IGNORE_HTTPS_ERRORS", false),
+ headless: readBooleanEnv("E2E_HEADLESS", isCI),
+ debug,
+ slowMoMs: debug ? readNumberEnv("E2E_SLOW_MO_MS", 500) : 0,
+ remoteTarget: readBooleanEnv("E2E_REMOTE_TARGET", false),
+ isCI
+} as const;
diff --git a/e2e/fixtures/test.ts b/e2e/fixtures/test.ts
new file mode 100644
index 0000000..b015793
--- /dev/null
+++ b/e2e/fixtures/test.ts
@@ -0,0 +1,11 @@
+import { expect, test as base } from "@playwright/test";
+import { env } from "./env.js";
+
+export const test = base.extend({
+ baseURL: async ({}, use) => {
+ await use(env.frontendUrl);
+ }
+});
+
+export { expect };
+
diff --git a/e2e/fixtures/users.ts b/e2e/fixtures/users.ts
new file mode 100644
index 0000000..678a96b
--- /dev/null
+++ b/e2e/fixtures/users.ts
@@ -0,0 +1,14 @@
+export const users = {
+ admin: {
+ username: "admin",
+ password: "admin123",
+ role: "admin",
+ storageState: ".auth/admin.json"
+ },
+ user: {
+ username: "e2euser",
+ email: "e2euser@clawmanager.local",
+ password: "user12345",
+ role: "user"
+ }
+} as const;
diff --git a/e2e/package-lock.json b/e2e/package-lock.json
new file mode 100644
index 0000000..7003bff
--- /dev/null
+++ b/e2e/package-lock.json
@@ -0,0 +1,767 @@
+{
+ "name": "clawmanager-e2e",
+ "version": "0.0.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "clawmanager-e2e",
+ "version": "0.0.0",
+ "devDependencies": {
+ "@playwright/test": "^1.49.1",
+ "@types/node": "^24.12.0",
+ "mysql2": "^3.11.5",
+ "tsx": "^4.19.2",
+ "typescript": "^5.9.3"
+ }
+ },
+ "node_modules/@esbuild/aix-ppc64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
+ "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "aix"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
+ "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
+ "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
+ "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
+ "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
+ "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
+ "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
+ "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
+ "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
+ "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ia32": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
+ "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-loong64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
+ "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-mips64el": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
+ "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+ "cpu": [
+ "mips64el"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ppc64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
+ "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-riscv64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
+ "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-s390x": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
+ "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
+ "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
+ "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
+ "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
+ "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
+ "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openharmony-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
+ "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/sunos-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
+ "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "sunos"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-arm64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
+ "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-ia32": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
+ "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-x64": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
+ "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@playwright/test": {
+ "version": "1.60.0",
+ "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.60.0.tgz",
+ "integrity": "sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "playwright": "1.60.0"
+ },
+ "bin": {
+ "playwright": "cli.js"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@types/node": {
+ "version": "24.12.4",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.4.tgz",
+ "integrity": "sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~7.16.0"
+ }
+ },
+ "node_modules/aws-ssl-profiles": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/aws-ssl-profiles/-/aws-ssl-profiles-1.1.2.tgz",
+ "integrity": "sha512-NZKeq9AfyQvEeNlN0zSYAaWrmBffJh3IELMZfRpJVWgrpEbtEpnjvzqBPf+mxoI287JohRDoa+/nsfqqiZmF6g==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 6.0.0"
+ }
+ },
+ "node_modules/denque": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/denque/-/denque-2.1.0.tgz",
+ "integrity": "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=0.10"
+ }
+ },
+ "node_modules/esbuild": {
+ "version": "0.28.0",
+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
+ "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "bin": {
+ "esbuild": "bin/esbuild"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "optionalDependencies": {
+ "@esbuild/aix-ppc64": "0.28.0",
+ "@esbuild/android-arm": "0.28.0",
+ "@esbuild/android-arm64": "0.28.0",
+ "@esbuild/android-x64": "0.28.0",
+ "@esbuild/darwin-arm64": "0.28.0",
+ "@esbuild/darwin-x64": "0.28.0",
+ "@esbuild/freebsd-arm64": "0.28.0",
+ "@esbuild/freebsd-x64": "0.28.0",
+ "@esbuild/linux-arm": "0.28.0",
+ "@esbuild/linux-arm64": "0.28.0",
+ "@esbuild/linux-ia32": "0.28.0",
+ "@esbuild/linux-loong64": "0.28.0",
+ "@esbuild/linux-mips64el": "0.28.0",
+ "@esbuild/linux-ppc64": "0.28.0",
+ "@esbuild/linux-riscv64": "0.28.0",
+ "@esbuild/linux-s390x": "0.28.0",
+ "@esbuild/linux-x64": "0.28.0",
+ "@esbuild/netbsd-arm64": "0.28.0",
+ "@esbuild/netbsd-x64": "0.28.0",
+ "@esbuild/openbsd-arm64": "0.28.0",
+ "@esbuild/openbsd-x64": "0.28.0",
+ "@esbuild/openharmony-arm64": "0.28.0",
+ "@esbuild/sunos-x64": "0.28.0",
+ "@esbuild/win32-arm64": "0.28.0",
+ "@esbuild/win32-ia32": "0.28.0",
+ "@esbuild/win32-x64": "0.28.0"
+ }
+ },
+ "node_modules/fsevents": {
+ "version": "2.3.2",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+ "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/generate-function": {
+ "version": "2.3.1",
+ "resolved": "https://registry.npmjs.org/generate-function/-/generate-function-2.3.1.tgz",
+ "integrity": "sha512-eeB5GfMNeevm/GRYq20ShmsaGcmI81kIX2K9XQx5miC8KdHaC6Jm0qQ8ZNeGOi7wYB8OsdxKs+Y2oVuTFuVwKQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "is-property": "^1.0.2"
+ }
+ },
+ "node_modules/iconv-lite": {
+ "version": "0.7.2",
+ "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
+ "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "safer-buffer": ">= 2.1.2 < 3.0.0"
+ },
+ "engines": {
+ "node": ">=0.10.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
+ }
+ },
+ "node_modules/is-property": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/is-property/-/is-property-1.0.2.tgz",
+ "integrity": "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/long": {
+ "version": "5.3.2",
+ "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+ "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+ "dev": true,
+ "license": "Apache-2.0"
+ },
+ "node_modules/lru.min": {
+ "version": "1.1.4",
+ "resolved": "https://registry.npmjs.org/lru.min/-/lru.min-1.1.4.tgz",
+ "integrity": "sha512-DqC6n3QQ77zdFpCMASA1a3Jlb64Hv2N2DciFGkO/4L9+q/IpIAuRlKOvCXabtRW6cQf8usbmM6BE/TOPysCdIA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "bun": ">=1.0.0",
+ "deno": ">=1.30.0",
+ "node": ">=8.0.0"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/sponsors/wellwelwel"
+ }
+ },
+ "node_modules/mysql2": {
+ "version": "3.22.4",
+ "resolved": "https://registry.npmjs.org/mysql2/-/mysql2-3.22.4.tgz",
+ "integrity": "sha512-CtXYlmL7ZamiYKbmqkamQHWJROUHSfm+f3kByzGfknw7kW51mcB2ouMUqYq1XfYxbXmnWo6RhPydx6OCqdgcmQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "aws-ssl-profiles": "^1.1.2",
+ "denque": "^2.1.0",
+ "generate-function": "^2.3.1",
+ "iconv-lite": "^0.7.2",
+ "long": "^5.3.2",
+ "lru.min": "^1.1.4",
+ "named-placeholders": "^1.1.6",
+ "sql-escaper": "^1.3.3"
+ },
+ "engines": {
+ "node": ">= 8.0"
+ },
+ "peerDependencies": {
+ "@types/node": ">= 8"
+ }
+ },
+ "node_modules/named-placeholders": {
+ "version": "1.1.6",
+ "resolved": "https://registry.npmjs.org/named-placeholders/-/named-placeholders-1.1.6.tgz",
+ "integrity": "sha512-Tz09sEL2EEuv5fFowm419c1+a/jSMiBjI9gHxVLrVdbUkkNUUfjsVYs9pVZu5oCon/kmRh9TfLEObFtkVxmY0w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "lru.min": "^1.1.0"
+ },
+ "engines": {
+ "node": ">=8.0.0"
+ }
+ },
+ "node_modules/playwright": {
+ "version": "1.60.0",
+ "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.60.0.tgz",
+ "integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "playwright-core": "1.60.0"
+ },
+ "bin": {
+ "playwright": "cli.js"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "optionalDependencies": {
+ "fsevents": "2.3.2"
+ }
+ },
+ "node_modules/playwright-core": {
+ "version": "1.60.0",
+ "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.60.0.tgz",
+ "integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "playwright-core": "cli.js"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/safer-buffer": {
+ "version": "2.1.2",
+ "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+ "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/sql-escaper": {
+ "version": "1.3.3",
+ "resolved": "https://registry.npmjs.org/sql-escaper/-/sql-escaper-1.3.3.tgz",
+ "integrity": "sha512-BsTCV265VpTp8tm1wyIm1xqQCS+Q9NHx2Sr+WcnUrgLrQ6yiDIvHYJV5gHxsj1lMBy2zm5twLaZao8Jd+S8JJw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "bun": ">=1.0.0",
+ "deno": ">=2.0.0",
+ "node": ">=12.0.0"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/mysqljs/sql-escaper?sponsor=1"
+ }
+ },
+ "node_modules/tsx": {
+ "version": "4.22.4",
+ "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.4.tgz",
+ "integrity": "sha512-X8EX+XV4QR5xCsrgxaED954zTDfY8KqlDtskKEL0cHhyS/P8b4IFOvGDQpsC9Q1XnLq915wEfwwY/zzskCtmhg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "esbuild": "~0.28.0"
+ },
+ "bin": {
+ "tsx": "dist/cli.mjs"
+ },
+ "engines": {
+ "node": ">=18.0.0"
+ },
+ "optionalDependencies": {
+ "fsevents": "~2.3.3"
+ }
+ },
+ "node_modules/tsx/node_modules/fsevents": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+ "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/undici-types": {
+ "version": "7.16.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
+ "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+ "dev": true,
+ "license": "MIT"
+ }
+ }
+}
diff --git a/e2e/package.json b/e2e/package.json
new file mode 100644
index 0000000..713c1dd
--- /dev/null
+++ b/e2e/package.json
@@ -0,0 +1,28 @@
+{
+ "name": "clawmanager-e2e",
+ "private": true,
+ "version": "0.0.0",
+ "type": "module",
+ "scripts": {
+ "test:p0": "tsx scripts/run-with-log.ts p0",
+ "test:p1": "tsx scripts/run-with-log.ts p1",
+ "test:p2": "tsx scripts/run-with-log.ts p2",
+ "test:all": "tsx scripts/run-with-log.ts all",
+ "ci:p0": "tsx scripts/run-with-log.ts p0 --ci",
+ "target": "tsx scripts/run-target.ts",
+ "test:target-script": "tsx scripts/runner-utils.test.ts && tsx scripts/run-with-log.test.ts && tsx scripts/run-target.test.ts",
+ "pw:p0": "playwright test --grep @p0",
+ "pw:p1": "playwright test --grep @p1",
+ "pw:p2": "playwright test --grep @p2",
+ "pw:all": "playwright test",
+ "test:report": "playwright show-report playwright-report",
+ "db:reset": "tsx scripts/reset-db.ts"
+ },
+ "devDependencies": {
+ "@playwright/test": "^1.49.1",
+ "@types/node": "^24.12.0",
+ "mysql2": "^3.11.5",
+ "tsx": "^4.19.2",
+ "typescript": "^5.9.3"
+ }
+}
diff --git a/e2e/pages/AdminRuntimePodsPage.ts b/e2e/pages/AdminRuntimePodsPage.ts
new file mode 100644
index 0000000..9a7d72c
--- /dev/null
+++ b/e2e/pages/AdminRuntimePodsPage.ts
@@ -0,0 +1,64 @@
+import type { Page } from "@playwright/test";
+import type { RuntimePodRegisterRequest } from "../fixtures/apiClient.js";
+import { expect } from "../fixtures/test.js";
+
+export class AdminRuntimePodsPage {
+ constructor(private readonly page: Page) {}
+
+ private main() {
+ return this.page.getByRole("main");
+ }
+
+ private podCard(podName: string) {
+ return this.main().locator("article", { hasText: podName }).first();
+ }
+
+ private formatRuntimeType(runtimeType: RuntimePodRegisterRequest["runtime_type"]) {
+ return runtimeType === "hermes" ? "Hermes" : "OpenClaw";
+ }
+
+ async goto() {
+ await this.page.goto("/admin/runtime-pods");
+ }
+
+ async expectVisible() {
+ await expect(this.page.getByRole("heading", { name: /^runtime$/i })).toBeVisible();
+ }
+
+ async expectEmptyState() {
+ await this.expectVisible();
+ await expect(this.main().getByText("No active runtime pods")).toBeVisible();
+ }
+
+ async selectRuntimeFilter(label: "All" | "OpenClaw" | "Hermes") {
+ await this.main().getByRole("button", { name: label }).click();
+ }
+
+ async expectPodVisible(podName: string) {
+ await this.expectVisible();
+ const card = this.podCard(podName);
+
+ await expect(card).toBeVisible();
+ await expect(card.getByRole("heading", { name: podName, exact: true })).toBeVisible();
+ }
+
+ async expectPodStatusAndCapacity(pod: RuntimePodRegisterRequest) {
+ await this.expectPodVisible(pod.pod_name);
+ const card = this.podCard(pod.pod_name);
+
+ await expect(card.getByText(this.formatRuntimeType(pod.runtime_type), { exact: true })).toBeVisible();
+ await expect(card.getByText(pod.draining ? "draining" : pod.state, { exact: true })).toBeVisible();
+ await expect(card.getByText("Slots", { exact: true })).toBeVisible();
+ await expect(card.getByText(`${pod.used_slots} / ${pod.capacity}`, { exact: true })).toBeVisible();
+ }
+
+ async expectPodMetricsVisible(podName: string) {
+ const card = this.podCard(podName);
+
+ await expect(card.getByText("CPU", { exact: true })).toBeVisible();
+ await expect(card.getByText("Memory", { exact: true })).toBeVisible();
+ await expect(card.getByText("Disk", { exact: true })).toBeVisible();
+ await expect(card.getByText("Network", { exact: true })).toBeVisible();
+ await expect(card.getByText(/Last seen/i)).toBeVisible();
+ }
+}
diff --git a/e2e/pages/LoginPage.ts b/e2e/pages/LoginPage.ts
new file mode 100644
index 0000000..3304a74
--- /dev/null
+++ b/e2e/pages/LoginPage.ts
@@ -0,0 +1,23 @@
+import type { Page } from "@playwright/test";
+import { expect } from "../fixtures/test.js";
+
+export class LoginPage {
+ constructor(private readonly page: Page) {}
+
+ async goto() {
+ await this.page.goto("/login");
+ }
+
+ async expectVisible() {
+ await expect(this.page.getByRole("heading", { name: /sign in to clawmanager/i })).toBeVisible();
+ await expect(this.page.getByLabel(/username/i)).toBeVisible();
+ await expect(this.page.getByLabel(/password/i)).toBeVisible();
+ }
+
+ async login(username: string, password: string) {
+ await this.page.getByLabel(/username/i).fill(username);
+ await this.page.getByLabel(/password/i).fill(password);
+ await this.page.getByRole("button", { name: /^sign in$/i }).click();
+ }
+}
+
diff --git a/e2e/playwright.config.ts b/e2e/playwright.config.ts
new file mode 100644
index 0000000..19e3287
--- /dev/null
+++ b/e2e/playwright.config.ts
@@ -0,0 +1,63 @@
+import path from "node:path";
+import { defineConfig, devices } from "@playwright/test";
+import { env, e2eRoot, reportsDir } from "./fixtures/env.js";
+
+const setupProjects = [
+ {
+ name: "auth setup",
+ testMatch: /setup\/auth\.setup\.ts/
+ },
+ ...(
+ env.remoteTarget
+ ? []
+ : [
+ {
+ name: "db setup",
+ testMatch: /setup\/db\.setup\.ts/
+ }
+ ]
+ )
+];
+
+export default defineConfig({
+ testDir: ".",
+ outputDir: "test-results",
+ timeout: env.remoteTarget ? 90_000 : 30_000,
+ expect: {
+ timeout: env.remoteTarget ? 45_000 : 10_000
+ },
+ fullyParallel: false,
+ retries: env.isCI ? 1 : 0,
+ workers: env.isCI ? 1 : undefined,
+ reporter: [
+ ["list"],
+ ["html", { outputFolder: "playwright-report", open: "never" }],
+ ["json", { outputFile: path.join(reportsDir, "results.json") }],
+ ["junit", { outputFile: path.join(reportsDir, "junit.xml") }]
+ ],
+ use: {
+ baseURL: env.frontendUrl,
+ headless: env.headless,
+ ignoreHTTPSErrors: env.ignoreHttpsErrors,
+ launchOptions: env.debug ? { slowMo: env.slowMoMs } : undefined,
+ trace: "retain-on-failure",
+ screenshot: "only-on-failure",
+ video: "retain-on-failure"
+ },
+ projects: [
+ ...setupProjects,
+ {
+ name: "chromium",
+ testMatch: /tests\/.*\.spec\.ts/,
+ dependencies: env.remoteTarget ? ["auth setup"] : ["auth setup", "db setup"],
+ use: {
+ ...devices["Desktop Chrome"]
+ }
+ }
+ ],
+ metadata: {
+ e2eRoot,
+ frontendUrl: env.frontendUrl,
+ backendUrl: env.backendUrl
+ }
+});
diff --git a/e2e/reports/.gitkeep b/e2e/reports/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/e2e/reports/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/e2e/scripts/e2e-down.ps1 b/e2e/scripts/e2e-down.ps1
new file mode 100644
index 0000000..9579a7f
--- /dev/null
+++ b/e2e/scripts/e2e-down.ps1
@@ -0,0 +1,10 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+Push-Location (Join-Path $PSScriptRoot "..")
+try {
+ docker compose -f docker/docker-compose.e2e.yml down --remove-orphans
+} finally {
+ Pop-Location
+}
+
diff --git a/e2e/scripts/e2e-down.sh b/e2e/scripts/e2e-down.sh
new file mode 100644
index 0000000..e8a7704
--- /dev/null
+++ b/e2e/scripts/e2e-down.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+set -eu
+
+cd "$(dirname "$0")/.."
+docker compose -f docker/docker-compose.e2e.yml down --remove-orphans
+
diff --git a/e2e/scripts/e2e-up.ps1 b/e2e/scripts/e2e-up.ps1
new file mode 100644
index 0000000..9a8c05e
--- /dev/null
+++ b/e2e/scripts/e2e-up.ps1
@@ -0,0 +1,10 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+Push-Location (Join-Path $PSScriptRoot "..")
+try {
+ docker compose -f docker/docker-compose.e2e.yml up -d mysql
+} finally {
+ Pop-Location
+}
+
diff --git a/e2e/scripts/e2e-up.sh b/e2e/scripts/e2e-up.sh
new file mode 100644
index 0000000..00b8282
--- /dev/null
+++ b/e2e/scripts/e2e-up.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+set -eu
+
+cd "$(dirname "$0")/.."
+docker compose -f docker/docker-compose.e2e.yml up -d mysql
+
diff --git a/e2e/scripts/reset-db.ts b/e2e/scripts/reset-db.ts
new file mode 100644
index 0000000..d3ceca4
--- /dev/null
+++ b/e2e/scripts/reset-db.ts
@@ -0,0 +1,50 @@
+import mysql from "mysql2/promise";
+import { env } from "../fixtures/env.js";
+import { sleep, waitForTcpPort } from "./wait-for.js";
+
+async function main() {
+ await waitForTcpPort(env.db.host, env.db.port, 120_000);
+
+ let connection: mysql.Connection | undefined;
+ let lastError: unknown;
+
+ for (let attempt = 1; attempt <= 30; attempt += 1) {
+ try {
+ connection = await mysql.createConnection({
+ host: env.db.host,
+ port: env.db.port,
+ user: env.db.user,
+ password: env.db.password,
+ multipleStatements: false
+ });
+ break;
+ } catch (error) {
+ lastError = error;
+ await sleep(2000);
+ }
+ }
+
+ if (!connection) {
+ throw new Error(
+ `failed to connect to MySQL: ${
+ lastError instanceof Error ? lastError.message : String(lastError)
+ }`
+ );
+ }
+
+ try {
+ await connection.query(`DROP DATABASE IF EXISTS \`${env.db.database}\``);
+ await connection.query(
+ `CREATE DATABASE \`${env.db.database}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`
+ );
+ console.log(`[e2e] reset database ${env.db.database}`);
+ } finally {
+ await connection.end();
+ }
+}
+
+main().catch((error: unknown) => {
+ console.error("[e2e] failed to reset database");
+ console.error(error instanceof Error ? error.message : String(error));
+ process.exit(1);
+});
diff --git a/e2e/scripts/run-target.test.ts b/e2e/scripts/run-target.test.ts
new file mode 100644
index 0000000..3418475
--- /dev/null
+++ b/e2e/scripts/run-target.test.ts
@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { buildTargetRunOptions } from "./run-target.js";
+
+const defaultOptions = buildTargetRunOptions(["172.16.1.12:39443"], {});
+
+assert.equal(defaultOptions.frontendUrl, "https://172.16.1.12:39443");
+assert.equal(defaultOptions.backendUrl, "https://172.16.1.12:39443/api/v1");
+assert.deepEqual(defaultOptions.playwrightArgs, [
+ "playwright",
+ "test",
+ "--grep",
+ "@p0",
+ "--grep-invert",
+ "@local-only",
+ "--workers=1"
+]);
+assert.equal(defaultOptions.env.E2E_FRONTEND_URL, "https://172.16.1.12:39443");
+assert.equal(defaultOptions.env.E2E_BACKEND_URL, "https://172.16.1.12:39443/api/v1");
+assert.equal(defaultOptions.env.E2E_IGNORE_HTTPS_ERRORS, "true");
+assert.equal(defaultOptions.env.E2E_HEADLESS, "false");
+assert.equal(defaultOptions.env.E2E_DEBUG, "false");
+assert.equal(defaultOptions.env.E2E_SLOW_MO_MS, "0");
+assert.equal(defaultOptions.debug, false);
+assert.equal(defaultOptions.slowMoMs, 0);
+
+const httpOptions = buildTargetRunOptions(["http://172.16.1.12:39080/"]);
+assert.equal(httpOptions.frontendUrl, "http://172.16.1.12:39080");
+assert.equal(httpOptions.backendUrl, "http://172.16.1.12:39080/api/v1");
+
+const headlessOptions = buildTargetRunOptions(["172.16.1.12:39443", "--headless"], {});
+assert.equal(headlessOptions.env.E2E_HEADLESS, "true");
+
+const headedOptions = buildTargetRunOptions(["172.16.1.12:39443", "--headless=false"], {});
+assert.equal(headedOptions.env.E2E_HEADLESS, "false");
+
+const ciOptions = buildTargetRunOptions(["172.16.1.12:39443"], { CI: "true" });
+assert.equal(ciOptions.env.E2E_HEADLESS, "true");
+
+const debugOptions = buildTargetRunOptions(["172.16.1.12:39443", "--debug"], {});
+assert.equal(debugOptions.env.E2E_DEBUG, "true");
+assert.equal(debugOptions.env.E2E_SLOW_MO_MS, "500");
+assert.equal(debugOptions.env.E2E_HEADLESS, "false");
+assert.equal(debugOptions.debug, true);
+assert.equal(debugOptions.slowMoMs, 500);
+
+assert.throws(() => buildTargetRunOptions([]), /Usage/);
+assert.throws(() => buildTargetRunOptions(["https://a.example", "https://b.example"]), /only accepts one address/);
diff --git a/e2e/scripts/run-target.ts b/e2e/scripts/run-target.ts
new file mode 100644
index 0000000..beed1e1
--- /dev/null
+++ b/e2e/scripts/run-target.ts
@@ -0,0 +1,117 @@
+import { pathToFileURL } from "node:url";
+import { e2eRoot } from "../fixtures/env.js";
+import {
+ createLogger,
+ DEBUG_SLOW_MO_MS,
+ defaultHeadlessFromEnv,
+ parseDebugArgs,
+ parseHeadlessArgs,
+ runCommand,
+ suiteArgs,
+ writeFailureScreenshotSummary
+} from "./runner-utils.js";
+
+export interface TargetRunOptions {
+ frontendUrl: string;
+ backendUrl: string;
+ headless: boolean;
+ debug: boolean;
+ slowMoMs: number;
+ playwrightArgs: string[];
+ env: NodeJS.ProcessEnv;
+}
+
+function withoutTrailingSlash(value: string) {
+ return value.replace(/\/+$/, "");
+}
+
+function normalizeTargetAddress(rawAddress: string) {
+ const trimmed = rawAddress.trim();
+ if (!trimmed) {
+ throw new Error("Usage: npm run target -- ");
+ }
+
+ const withProtocol = /^[a-z][a-z\d+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+ const url = new URL(withProtocol);
+ url.hash = "";
+ url.search = "";
+ return withoutTrailingSlash(url.toString());
+}
+
+export function buildTargetRunOptions(
+ args: string[] = process.argv.slice(2),
+ environment: NodeJS.ProcessEnv = process.env
+): TargetRunOptions {
+ const parsedHeadless = parseHeadlessArgs(args, defaultHeadlessFromEnv(environment));
+ const parsedDebug = parseDebugArgs(parsedHeadless.args, false);
+ const remainingArgs = parsedDebug.args;
+
+ if (remainingArgs.length === 0) {
+ throw new Error("Usage: npm run target -- ");
+ }
+ if (remainingArgs.length > 1) {
+ throw new Error("target runner only accepts one address plus optional --headless/--headed/--debug");
+ }
+
+ const frontendUrl = normalizeTargetAddress(remainingArgs[0]);
+ const backendUrl = `${frontendUrl}/api/v1`;
+ const slowMoMs = parsedDebug.debug ? DEBUG_SLOW_MO_MS : 0;
+
+ return {
+ frontendUrl,
+ backendUrl,
+ headless: parsedHeadless.headless,
+ debug: parsedDebug.debug,
+ slowMoMs,
+ playwrightArgs: ["playwright", "test", ...suiteArgs("p0"), "--grep-invert", "@local-only", "--workers=1"],
+ env: {
+ ...environment,
+ E2E_FRONTEND_URL: frontendUrl,
+ E2E_BACKEND_URL: backendUrl,
+ E2E_CI: "true",
+ E2E_HEADLESS: String(parsedHeadless.headless),
+ E2E_DEBUG: String(parsedDebug.debug),
+ E2E_SLOW_MO_MS: String(slowMoMs),
+ E2E_IGNORE_HTTPS_ERRORS: "true",
+ E2E_REMOTE_TARGET: "true"
+ }
+ };
+}
+
+async function main() {
+ const options = buildTargetRunOptions();
+ const logger = createLogger("target-run.log");
+
+ try {
+ logger.log(`target frontend: ${options.frontendUrl}`);
+ logger.log(`target backend: ${options.backendUrl}`);
+ logger.log(`target headless: ${options.headless}`);
+ logger.log(`target debug: ${options.debug} slowMoMs=${options.slowMoMs}`);
+ logger.log("running remote Playwright P0 suite");
+ try {
+ await runCommand(
+ "npx",
+ options.playwrightArgs,
+ {
+ cwd: e2eRoot,
+ label: "playwright",
+ env: options.env
+ },
+ logger.write
+ );
+ } catch (error) {
+ writeFailureScreenshotSummary(logger.write);
+ throw error;
+ }
+ logger.log("target e2e run completed successfully");
+ } finally {
+ await logger.close();
+ }
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+ main().catch((error: unknown) => {
+ console.error(error instanceof Error ? error.message : String(error));
+ process.exit(1);
+ });
+}
diff --git a/e2e/scripts/run-with-log.test.ts b/e2e/scripts/run-with-log.test.ts
new file mode 100644
index 0000000..2e9fbdc
--- /dev/null
+++ b/e2e/scripts/run-with-log.test.ts
@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { parseArgs } from "./run-with-log.js";
+
+assert.deepEqual(parseArgs(["p0"], {}), {
+ suite: "p0",
+ ci: false,
+ headless: false,
+ debug: false,
+ slowMoMs: 0,
+ extraArgs: []
+});
+
+assert.deepEqual(parseArgs(["p1", "--headless", "--workers=1"], {}), {
+ suite: "p1",
+ ci: false,
+ headless: true,
+ debug: false,
+ slowMoMs: 0,
+ extraArgs: ["--workers=1"]
+});
+
+assert.deepEqual(parseArgs(["p2", "--headed", "--workers=1"], { CI: "true" }), {
+ suite: "p2",
+ ci: false,
+ headless: false,
+ debug: false,
+ slowMoMs: 0,
+ extraArgs: ["--workers=1"]
+});
+
+assert.deepEqual(parseArgs(["all", "--ci"], {}), {
+ suite: "all",
+ ci: true,
+ headless: true,
+ debug: false,
+ slowMoMs: 0,
+ extraArgs: []
+});
+
+assert.deepEqual(parseArgs(["p0", "--ci", "--headless=false"], {}), {
+ suite: "p0",
+ ci: true,
+ headless: false,
+ debug: false,
+ slowMoMs: 0,
+ extraArgs: []
+});
+
+assert.deepEqual(parseArgs(["p0", "--debug", "--workers=1"], {}), {
+ suite: "p0",
+ ci: false,
+ headless: false,
+ debug: true,
+ slowMoMs: 500,
+ extraArgs: ["--workers=1"]
+});
diff --git a/e2e/scripts/run-with-log.ts b/e2e/scripts/run-with-log.ts
new file mode 100644
index 0000000..e9f0359
--- /dev/null
+++ b/e2e/scripts/run-with-log.ts
@@ -0,0 +1,181 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { env, e2eRoot, repoRoot } from "../fixtures/env.js";
+import { waitForHttpStatus, waitForTcpPort } from "./wait-for.js";
+import {
+ createLogger,
+ DEBUG_SLOW_MO_MS,
+ defaultHeadlessFromEnv,
+ parseDebugArgs,
+ parseHeadlessArgs,
+ runCommand,
+ startService,
+ stopService,
+ suiteArgs,
+ type Suite,
+ writeFailureScreenshotSummary
+} from "./runner-utils.js";
+
+const npmCmd = "npm";
+const npxCmd = "npx";
+const goCmd = "go";
+
+function childEnv(extra: NodeJS.ProcessEnv = {}) {
+ return {
+ ...process.env,
+ E2E_FRONTEND_URL: env.frontendUrl,
+ E2E_BACKEND_URL: env.backendUrl,
+ E2E_DB_HOST: env.db.host,
+ E2E_DB_PORT: String(env.db.port),
+ E2E_DB_USER: env.db.user,
+ E2E_DB_PASSWORD: env.db.password,
+ E2E_DB_NAME: env.db.database,
+ E2E_RUNTIME_AGENT_TOKEN: env.runtimeAgentToken,
+ E2E_WORKSPACE_ROOT: env.workspaceRoot,
+ E2E_OBJECT_STORAGE_FALLBACK: env.objectStorageFallback,
+ ...extra
+ };
+}
+
+export function parseArgs(
+ args: string[] = process.argv.slice(2),
+ environment: NodeJS.ProcessEnv = process.env
+): { suite: Suite; ci: boolean; headless: boolean; debug: boolean; slowMoMs: number; extraArgs: string[] } {
+ const [suiteArg = "p0", ...rest] = args;
+ if (!["p0", "p1", "p2", "all"].includes(suiteArg)) {
+ throw new Error(`unknown e2e suite: ${suiteArg}`);
+ }
+ const ci = rest.includes("--ci");
+ const filteredArgs = rest.filter((value) => value !== "--ci" && value !== "--");
+ const parsedHeadless = parseHeadlessArgs(
+ filteredArgs,
+ ci || defaultHeadlessFromEnv(environment)
+ );
+ const parsedDebug = parseDebugArgs(parsedHeadless.args, false);
+ return {
+ suite: suiteArg as Suite,
+ ci,
+ headless: parsedHeadless.headless,
+ debug: parsedDebug.debug,
+ slowMoMs: parsedDebug.debug ? DEBUG_SLOW_MO_MS : 0,
+ extraArgs: parsedDebug.args
+ };
+}
+
+function frontendHostAndPort() {
+ const url = new URL(env.frontendUrl);
+ return {
+ host: url.hostname,
+ port: url.port || (url.protocol === "https:" ? "443" : "80")
+ };
+}
+
+async function main() {
+ const { suite, ci, headless, debug, slowMoMs, extraArgs } = parseArgs();
+ const logger = createLogger();
+ let backend: ChildProcessWithoutNullStreams | undefined;
+ let frontend: ChildProcessWithoutNullStreams | undefined;
+
+ try {
+ logger.log(`starting e2e suite=${suite} ci=${ci} headless=${headless} debug=${debug} slowMoMs=${slowMoMs}`);
+ logger.log(`run log: ${logger.logPath}`);
+
+ logger.log("starting MySQL");
+ await runCommand(
+ "docker",
+ ["compose", "-f", "docker/docker-compose.e2e.yml", "up", "-d", "mysql"],
+ { cwd: e2eRoot, label: "docker" },
+ logger.write
+ );
+ await waitForTcpPort(env.db.host, env.db.port, 120_000);
+
+ logger.log("resetting e2e database");
+ await runCommand(npxCmd, ["tsx", "scripts/reset-db.ts"], { cwd: e2eRoot, label: "db" }, logger.write);
+
+ logger.log("starting backend");
+ backend = startService(
+ goCmd,
+ ["run", "./cmd/server"],
+ {
+ cwd: path.join(repoRoot, "backend"),
+ label: "backend",
+ env: childEnv({
+ SERVER_ADDRESS: ":9001",
+ DB_HOST: env.db.host,
+ DB_PORT: String(env.db.port),
+ DB_USER: env.db.user,
+ DB_PASSWORD: env.db.password,
+ DB_NAME: env.db.database,
+ JWT_SECRET: "clawmanager-e2e-secret",
+ RUNTIME_SCHEDULER_ENABLED: "false",
+ RUNTIME_AGENT_REPORT_TOKEN: env.runtimeAgentToken,
+ RUNTIME_WORKSPACE_ROOT: env.workspaceRoot,
+ OBJECT_STORAGE_LOCAL_FALLBACK: env.objectStorageFallback,
+ SKILL_SCANNER_ENABLED: "false"
+ })
+ },
+ logger.write
+ );
+ await waitForTcpPort("127.0.0.1", 9001, 120_000);
+
+ logger.log("starting frontend");
+ const frontendTarget = frontendHostAndPort();
+ frontend = startService(
+ npmCmd,
+ ["run", "dev", "--", "--host", frontendTarget.host, "--port", frontendTarget.port, "--strictPort"],
+ { cwd: path.join(repoRoot, "frontend"), label: "frontend", env: childEnv() },
+ logger.write
+ );
+ await waitForHttpStatus(env.frontendUrl, 200, 120_000);
+
+ logger.log("running Playwright");
+ const args = ["playwright", "test", ...suiteArgs(suite)];
+ if (ci && !extraArgs.some((value) => value.startsWith("--workers"))) {
+ args.push("--workers=1");
+ }
+ args.push(...extraArgs);
+ try {
+ await runCommand(
+ npxCmd,
+ args,
+ {
+ cwd: e2eRoot,
+ label: "playwright",
+ env: childEnv({
+ CI: ci ? "true" : process.env.CI,
+ E2E_HEADLESS: String(headless),
+ E2E_DEBUG: String(debug),
+ E2E_SLOW_MO_MS: String(slowMoMs)
+ })
+ },
+ logger.write
+ );
+ } catch (error) {
+ writeFailureScreenshotSummary(logger.write);
+ throw error;
+ }
+
+ logger.log("e2e run completed successfully");
+ } finally {
+ logger.log("cleaning up e2e services");
+ await stopService(frontend, "frontend");
+ await stopService(backend, "backend");
+ await runCommand(
+ "docker",
+ ["compose", "-f", "docker/docker-compose.e2e.yml", "down", "--remove-orphans"],
+ { cwd: e2eRoot, label: "docker" },
+ logger.write
+ ).catch((error: unknown) => {
+ logger.log(`docker cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+ });
+ await logger.close();
+ }
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+ main().catch((error: unknown) => {
+ console.error(error instanceof Error ? error.message : String(error));
+ process.exit(1);
+ });
+}
diff --git a/e2e/scripts/runner-utils.test.ts b/e2e/scripts/runner-utils.test.ts
new file mode 100644
index 0000000..68bd885
--- /dev/null
+++ b/e2e/scripts/runner-utils.test.ts
@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import assert from "node:assert/strict";
+import { findFailureScreenshots, parseDebugArgs, parseHeadlessArgs } from "./runner-utils.js";
+
+assert.deepEqual(parseHeadlessArgs([], false), {
+ headless: false,
+ args: []
+});
+
+assert.deepEqual(parseHeadlessArgs([], true), {
+ headless: true,
+ args: []
+});
+
+assert.deepEqual(parseHeadlessArgs(["--headless", "--workers=1"], false), {
+ headless: true,
+ args: ["--workers=1"]
+});
+
+assert.deepEqual(parseHeadlessArgs(["--headless=false", "--workers=1"], true), {
+ headless: false,
+ args: ["--workers=1"]
+});
+
+assert.deepEqual(parseHeadlessArgs(["--headless", "false", "--workers=1"], true), {
+ headless: false,
+ args: ["--workers=1"]
+});
+
+assert.deepEqual(parseHeadlessArgs(["--headed", "--workers=1"], true), {
+ headless: false,
+ args: ["--workers=1"]
+});
+
+assert.throws(() => parseHeadlessArgs(["--headless=maybe"], false), /headless/);
+
+assert.deepEqual(parseDebugArgs([], false), {
+ debug: false,
+ args: []
+});
+
+assert.deepEqual(parseDebugArgs(["--debug", "--workers=1"], false), {
+ debug: true,
+ args: ["--workers=1"]
+});
+
+assert.deepEqual(parseDebugArgs(["--debug=false", "--workers=1"], true), {
+ debug: false,
+ args: ["--workers=1"]
+});
+
+assert.deepEqual(parseDebugArgs(["--debug", "false", "--workers=1"], true), {
+ debug: false,
+ args: ["--workers=1"]
+});
+
+assert.deepEqual(parseDebugArgs(["--no-debug", "--workers=1"], true), {
+ debug: false,
+ args: ["--workers=1"]
+});
+
+assert.throws(() => parseDebugArgs(["--debug=maybe"], false), /debug/);
+
+const screenshotRoot = fs.mkdtempSync(path.join(os.tmpdir(), "clawmanager-e2e-screenshots-"));
+const nestedDir = path.join(screenshotRoot, "failed-test");
+fs.mkdirSync(nestedDir, { recursive: true });
+fs.writeFileSync(path.join(nestedDir, "test-failed-1.png"), "");
+fs.writeFileSync(path.join(nestedDir, "trace.zip"), "");
+fs.writeFileSync(path.join(screenshotRoot, "other.png"), "");
+
+assert.deepEqual(
+ findFailureScreenshots(screenshotRoot)
+ .map((filePath) => path.basename(filePath))
+ .sort(),
+ ["other.png", "test-failed-1.png"]
+);
diff --git a/e2e/scripts/runner-utils.ts b/e2e/scripts/runner-utils.ts
new file mode 100644
index 0000000..7239087
--- /dev/null
+++ b/e2e/scripts/runner-utils.ts
@@ -0,0 +1,278 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { reportsDir, testResultsDir } from "../fixtures/env.js";
+
+export type Suite = "p0" | "p1" | "p2" | "all";
+
+export const DEBUG_SLOW_MO_MS = 500;
+
+const isWindows = process.platform === "win32";
+const truthyValues = new Set(["1", "true", "yes", "on"]);
+const falsyValues = new Set(["0", "false", "no", "off"]);
+
+export function defaultHeadlessFromEnv(environment: NodeJS.ProcessEnv = process.env) {
+ return environment.CI === "true" || environment.E2E_CI === "true";
+}
+
+function parseBooleanFlag(flag: string, value: string) {
+ const normalized = value.trim().toLowerCase();
+ if (truthyValues.has(normalized)) {
+ return true;
+ }
+ if (falsyValues.has(normalized)) {
+ return false;
+ }
+ throw new Error(`${flag} must be true or false`);
+}
+
+export function parseHeadlessArgs(args: string[], defaultHeadless: boolean) {
+ let headless = defaultHeadless;
+ const remainingArgs: string[] = [];
+
+ for (let index = 0; index < args.length; index += 1) {
+ const arg = args[index];
+ if (arg === "--headless") {
+ const nextArg = args[index + 1];
+ const nextValue = nextArg?.toLowerCase();
+ if (nextValue && (truthyValues.has(nextValue) || falsyValues.has(nextValue))) {
+ headless = parseBooleanFlag("--headless", nextArg);
+ index += 1;
+ } else {
+ headless = true;
+ }
+ continue;
+ }
+ if (arg === "--headed" || arg === "--no-headless") {
+ headless = false;
+ continue;
+ }
+ if (arg.startsWith("--headless=")) {
+ headless = parseBooleanFlag("--headless", arg.slice("--headless=".length));
+ continue;
+ }
+ remainingArgs.push(arg);
+ }
+
+ return {
+ headless,
+ args: remainingArgs
+ };
+}
+
+export function parseDebugArgs(args: string[], defaultDebug: boolean) {
+ let debug = defaultDebug;
+ const remainingArgs: string[] = [];
+
+ for (let index = 0; index < args.length; index += 1) {
+ const arg = args[index];
+ if (arg === "--debug") {
+ const nextArg = args[index + 1];
+ const nextValue = nextArg?.toLowerCase();
+ if (nextValue && (truthyValues.has(nextValue) || falsyValues.has(nextValue))) {
+ debug = parseBooleanFlag("--debug", nextArg);
+ index += 1;
+ } else {
+ debug = true;
+ }
+ continue;
+ }
+ if (arg === "--no-debug") {
+ debug = false;
+ continue;
+ }
+ if (arg.startsWith("--debug=")) {
+ debug = parseBooleanFlag("--debug", arg.slice("--debug=".length));
+ continue;
+ }
+ remainingArgs.push(arg);
+ }
+
+ return {
+ debug,
+ args: remainingArgs
+ };
+}
+
+export function findFailureScreenshots(rootDir = testResultsDir) {
+ if (!fs.existsSync(rootDir)) {
+ return [];
+ }
+
+ const screenshots: string[] = [];
+ const visit = (dir: string) => {
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ const entryPath = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ visit(entryPath);
+ } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".png")) {
+ screenshots.push(entryPath);
+ }
+ }
+ };
+
+ visit(rootDir);
+ return screenshots.sort((a, b) => a.localeCompare(b));
+}
+
+export function writeFailureScreenshotSummary(write: (line: string) => void) {
+ const screenshots = findFailureScreenshots();
+ if (screenshots.length === 0) {
+ write(`[e2e] no failure screenshots found in ${testResultsDir}\n`);
+ return;
+ }
+
+ write(`[e2e] failure screenshot evidence:\n`);
+ for (const screenshot of screenshots) {
+ write(`[e2e] ${screenshot}\n`);
+ }
+}
+
+function timestamp() {
+ return new Date().toISOString();
+}
+
+export function createLogger(fileName = "run.log") {
+ fs.mkdirSync(reportsDir, { recursive: true });
+ const logPath = path.join(reportsDir, fileName);
+ const stream = fs.createWriteStream(logPath, { flags: "w" });
+
+ const write = (line: string) => {
+ stream.write(line);
+ process.stdout.write(line);
+ };
+
+ const log = (message: string) => {
+ write(`[${timestamp()}] ${message}\n`);
+ };
+
+ return {
+ logPath,
+ log,
+ write,
+ close: () =>
+ new Promise((resolve) => {
+ stream.end(resolve);
+ })
+ };
+}
+
+function pipeChild(
+ child: ChildProcessWithoutNullStreams,
+ label: string,
+ write: (line: string) => void
+) {
+ child.stdout.on("data", (chunk: Buffer) => {
+ write(chunk.toString().replace(/^/gm, `[${label}] `));
+ });
+ child.stderr.on("data", (chunk: Buffer) => {
+ write(chunk.toString().replace(/^/gm, `[${label}] `));
+ });
+}
+
+function quoteWindowsArg(value: string) {
+ if (/^[A-Za-z0-9_./:=@-]+$/.test(value)) {
+ return value;
+ }
+ return `"${value.replace(/"/g, '\\"')}"`;
+}
+
+function spawnPortable(
+ command: string,
+ args: string[],
+ options: { cwd: string; env?: NodeJS.ProcessEnv }
+): ChildProcessWithoutNullStreams {
+ if (!isWindows) {
+ return spawn(command, args, {
+ cwd: options.cwd,
+ env: options.env,
+ windowsHide: true
+ });
+ }
+
+ const commandLine = [command, ...args].map(quoteWindowsArg).join(" ");
+ return spawn("cmd.exe", ["/d", "/s", "/c", commandLine], {
+ cwd: options.cwd,
+ env: options.env,
+ windowsHide: true
+ });
+}
+
+export function runCommand(
+ command: string,
+ args: string[],
+ options: { cwd: string; env?: NodeJS.ProcessEnv; label: string },
+ write: (line: string) => void
+): Promise {
+ return new Promise((resolve, reject) => {
+ const child = spawnPortable(command, args, options);
+ pipeChild(child, options.label, write);
+ child.on("error", reject);
+ child.on("exit", (code) => {
+ if (code === 0) {
+ resolve();
+ } else {
+ reject(new Error(`${options.label} exited with code ${code}`));
+ }
+ });
+ });
+}
+
+export function startService(
+ command: string,
+ args: string[],
+ options: { cwd: string; env?: NodeJS.ProcessEnv; label: string },
+ write: (line: string) => void
+) {
+ const child = spawnPortable(command, args, options);
+ pipeChild(child, options.label, write);
+ return child;
+}
+
+async function killWindowsProcessTree(pid: number) {
+ await new Promise((resolve) => {
+ const child = spawn("taskkill.exe", ["/pid", String(pid), "/t", "/f"], {
+ windowsHide: true
+ });
+ child.on("exit", () => resolve());
+ child.on("error", () => resolve());
+ });
+}
+
+export async function stopService(
+ child: ChildProcessWithoutNullStreams | undefined,
+ label: string
+) {
+ if (!child || child.killed) {
+ return;
+ }
+
+ await new Promise((resolve) => {
+ child.once("exit", () => resolve());
+ if (isWindows && child.pid) {
+ void killWindowsProcessTree(child.pid).then(resolve);
+ } else {
+ child.kill();
+ }
+ setTimeout(() => {
+ if (!child.killed) {
+ child.kill("SIGKILL");
+ }
+ resolve();
+ }, 5000).unref();
+ });
+ console.log(`[e2e] stopped ${label}`);
+}
+
+export function suiteArgs(suite: Suite) {
+ switch (suite) {
+ case "p0":
+ return ["--grep", "@p0"];
+ case "p1":
+ return ["--grep", "@p1"];
+ case "p2":
+ return ["--grep", "@p2"];
+ case "all":
+ return [];
+ }
+}
diff --git a/e2e/scripts/wait-for.ts b/e2e/scripts/wait-for.ts
new file mode 100644
index 0000000..4a88b8d
--- /dev/null
+++ b/e2e/scripts/wait-for.ts
@@ -0,0 +1,70 @@
+import net from "node:net";
+
+export function sleep(ms: number) {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForTcpPort(
+ host: string,
+ port: number,
+ timeoutMs = 60_000
+): Promise {
+ const deadline = Date.now() + timeoutMs;
+ let lastError: unknown;
+
+ while (Date.now() < deadline) {
+ try {
+ await new Promise((resolve, reject) => {
+ const socket = net.createConnection({ host, port });
+ socket.setTimeout(2000);
+ socket.once("connect", () => {
+ socket.end();
+ resolve();
+ });
+ socket.once("timeout", () => {
+ socket.destroy();
+ reject(new Error(`timeout waiting for ${host}:${port}`));
+ });
+ socket.once("error", reject);
+ });
+ return;
+ } catch (error) {
+ lastError = error;
+ await sleep(1000);
+ }
+ }
+
+ throw new Error(
+ `timed out waiting for ${host}:${port}: ${
+ lastError instanceof Error ? lastError.message : String(lastError)
+ }`
+ );
+}
+
+export async function waitForHttpStatus(
+ url: string,
+ expectedStatus = 200,
+ timeoutMs = 60_000
+): Promise {
+ const deadline = Date.now() + timeoutMs;
+ let lastStatus = 0;
+ let lastError = "";
+
+ while (Date.now() < deadline) {
+ try {
+ const response = await fetch(url);
+ lastStatus = response.status;
+ if (response.status === expectedStatus) {
+ return;
+ }
+ } catch (error) {
+ lastError = error instanceof Error ? error.message : String(error);
+ }
+ await sleep(1000);
+ }
+
+ throw new Error(
+ `timed out waiting for ${url}; last status=${lastStatus}; last error=${lastError}`
+ );
+}
+
diff --git a/e2e/setup/auth.setup.ts b/e2e/setup/auth.setup.ts
new file mode 100644
index 0000000..e9f57e1
--- /dev/null
+++ b/e2e/setup/auth.setup.ts
@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { e2eRoot } from "../fixtures/env.js";
+import { test, expect } from "../fixtures/test.js";
+import { users } from "../fixtures/users.js";
+import { LoginPage } from "../pages/LoginPage.js";
+
+test("@p0 auth setup writes admin storage state", async ({ page }) => {
+ const loginPage = new LoginPage(page);
+ await test.step("open login page", async () => {
+ await loginPage.goto();
+ await loginPage.expectVisible();
+ });
+
+ await test.step("login as seeded admin", async () => {
+ await loginPage.login(users.admin.username, users.admin.password);
+ await expect
+ .poll(() => page.evaluate(() => window.localStorage.getItem("access_token")))
+ .toBeTruthy();
+ });
+
+ await test.step("write storage state", async () => {
+ const statePath = path.join(e2eRoot, users.admin.storageState);
+ fs.mkdirSync(path.dirname(statePath), { recursive: true });
+ await page.context().storageState({ path: statePath });
+ });
+});
+
diff --git a/e2e/setup/db.setup.ts b/e2e/setup/db.setup.ts
new file mode 100644
index 0000000..088c4ce
--- /dev/null
+++ b/e2e/setup/db.setup.ts
@@ -0,0 +1,11 @@
+import { test, expect } from "../fixtures/test.js";
+import { defaultRuntimePod, registerRuntimePod } from "../fixtures/apiClient.js";
+
+test("@p0 @local-only db setup registers runtime pod", async ({ request }) => {
+ await test.step("register deterministic runtime pod", async () => {
+ const pod = await registerRuntimePod(request);
+ expect(pod.pod_name).toBe(defaultRuntimePod.pod_name);
+ expect(pod.runtime_type).toBe("openclaw");
+ expect(pod.state).toBe("ready");
+ });
+});
diff --git a/e2e/tests/admin/access-control.spec.ts b/e2e/tests/admin/access-control.spec.ts
new file mode 100644
index 0000000..65a3cbc
--- /dev/null
+++ b/e2e/tests/admin/access-control.spec.ts
@@ -0,0 +1,37 @@
+import { login, registerUser } from "../../fixtures/apiClient.js";
+import { env } from "../../fixtures/env.js";
+import { test, expect } from "../../fixtures/test.js";
+import { users } from "../../fixtures/users.js";
+
+test("@p0 unauthenticated admin route redirects to login", async ({ page }) => {
+ await page.goto("/admin/runtime-pods");
+
+ await expect(page).toHaveURL(/\/login$/);
+});
+
+test("@p0 @local-only non-admin user cannot open admin routes", async ({ page, request }) => {
+ await registerUser(request, users.user);
+ const tokens = await login(request, users.user);
+
+ await page.addInitScript(
+ ({ accessToken, refreshToken }) => {
+ window.localStorage.setItem("access_token", accessToken);
+ window.localStorage.setItem("refresh_token", refreshToken);
+ },
+ { accessToken: tokens.access_token, refreshToken: tokens.refresh_token }
+ );
+
+ await page.goto(`${env.frontendUrl}/admin/runtime-pods`);
+
+ await expect(page).toHaveURL(/\/dashboard$/);
+});
+
+test.describe("admin access", () => {
+ test.use({ storageState: users.admin.storageState });
+
+ test("@p0 admin can open runtime pods route", async ({ page }) => {
+ await page.goto("/admin/runtime-pods");
+
+ await expect(page.getByRole("heading", { name: /^runtime$/i })).toBeVisible();
+ });
+});
diff --git a/e2e/tests/admin/runtime-pods.spec.ts b/e2e/tests/admin/runtime-pods.spec.ts
new file mode 100644
index 0000000..d922ad1
--- /dev/null
+++ b/e2e/tests/admin/runtime-pods.spec.ts
@@ -0,0 +1,23 @@
+import { defaultRuntimePod } from "../../fixtures/apiClient.js";
+import { test } from "../../fixtures/test.js";
+import { users } from "../../fixtures/users.js";
+import { AdminRuntimePodsPage } from "../../pages/AdminRuntimePodsPage.js";
+
+test.use({ storageState: users.admin.storageState });
+
+test("@p0 @local-only admin runtime pods page renders no runtime pods for an empty filter", async ({ page }) => {
+ const runtimePodsPage = new AdminRuntimePodsPage(page);
+
+ await runtimePodsPage.goto();
+ await runtimePodsPage.selectRuntimeFilter("Hermes");
+ await runtimePodsPage.expectEmptyState();
+});
+
+test("@p0 @local-only admin runtime pods page renders seeded pod status and capacity", async ({ page }) => {
+ const runtimePodsPage = new AdminRuntimePodsPage(page);
+
+ await runtimePodsPage.goto();
+ await runtimePodsPage.selectRuntimeFilter("OpenClaw");
+ await runtimePodsPage.expectPodStatusAndCapacity(defaultRuntimePod);
+ await runtimePodsPage.expectPodMetricsVisible(defaultRuntimePod.pod_name);
+});
diff --git a/e2e/tests/api/auth.spec.ts b/e2e/tests/api/auth.spec.ts
new file mode 100644
index 0000000..88eb393
--- /dev/null
+++ b/e2e/tests/api/auth.spec.ts
@@ -0,0 +1,26 @@
+import { getMe, getMeRaw, login } from "../../fixtures/apiClient.js";
+import { test, expect } from "../../fixtures/test.js";
+import { users } from "../../fixtures/users.js";
+
+test("@p0 auth login returns tokens", async ({ request }) => {
+ const tokens = await login(request);
+
+ expect(tokens.access_token).toBeTruthy();
+ expect(tokens.refresh_token).toBeTruthy();
+ expect(tokens.expires_in).toBeGreaterThan(0);
+});
+
+test("@p0 auth me returns current user with valid token", async ({ request }) => {
+ const tokens = await login(request);
+ const user = await getMe(request, tokens.access_token);
+
+ expect(user.username).toBe(users.admin.username);
+ expect(user.role).toBe(users.admin.role);
+});
+
+test("@p0 auth me rejects unauthenticated requests", async ({ request }) => {
+ const response = await getMeRaw(request);
+
+ expect(response.status()).toBe(401);
+});
+
diff --git a/e2e/tests/api/runtime-agent.spec.ts b/e2e/tests/api/runtime-agent.spec.ts
new file mode 100644
index 0000000..147e39b
--- /dev/null
+++ b/e2e/tests/api/runtime-agent.spec.ts
@@ -0,0 +1,49 @@
+import {
+ defaultRuntimePod,
+ listRuntimePods,
+ login,
+ postRuntimePodRegisterRaw,
+ registerRuntimePod,
+ sendRuntimeHeartbeat
+} from "../../fixtures/apiClient.js";
+import { test, expect } from "../../fixtures/test.js";
+
+test("@p0 @local-only runtime-agent register persists an openclaw runtime pod", async ({ request }) => {
+ const pod = await registerRuntimePod(request, {
+ pod_name: "e2e-openclaw-runtime-api-register"
+ });
+ const tokens = await login(request);
+ const pods = await listRuntimePods(request, tokens.access_token);
+
+ expect(pod.runtime_type).toBe("openclaw");
+ expect(pod.capacity).toBe(defaultRuntimePod.capacity);
+ expect(pod.used_slots).toBe(defaultRuntimePod.used_slots);
+ expect(pod.draining).toBe(defaultRuntimePod.draining);
+ expect(pods.some((item) => item.pod_name === "e2e-openclaw-runtime-api-register")).toBe(true);
+});
+
+test("@p0 @local-only runtime-agent heartbeat updates pod health state", async ({ request }) => {
+ const pod = await registerRuntimePod(request, {
+ pod_name: "e2e-openclaw-runtime-api-heartbeat"
+ });
+
+ await sendRuntimeHeartbeat(request, { pod_id: pod.id }, { state: "draining", used_slots: 3, draining: true });
+
+ const tokens = await login(request);
+ const pods = await listRuntimePods(request, tokens.access_token);
+ const updated = pods.find((item) => item.id === pod.id);
+
+ expect(updated?.state).toBe("draining");
+ expect(updated?.used_slots).toBe(3);
+ expect(updated?.draining).toBe(true);
+});
+
+test("@p0 @local-only runtime-agent register rejects unsupported runtime type", async ({ request }) => {
+ const response = await postRuntimePodRegisterRaw(request, {
+ ...defaultRuntimePod,
+ runtime_type: "ubuntu",
+ pod_name: "e2e-unsupported-runtime-api"
+ });
+
+ expect(response.status()).toBe(400);
+});
diff --git a/e2e/tests/instances/lite-pro-modes.spec.ts b/e2e/tests/instances/lite-pro-modes.spec.ts
new file mode 100644
index 0000000..5cb1a55
--- /dev/null
+++ b/e2e/tests/instances/lite-pro-modes.spec.ts
@@ -0,0 +1,405 @@
+import { expect, test } from "../../fixtures/test.js";
+import type { Page } from "@playwright/test";
+import type { InstanceRecord } from "../../fixtures/apiClient.js";
+import { users } from "../../fixtures/users.js";
+
+test.use({ storageState: users.admin.storageState });
+
+type InstanceMode = "lite" | "pro";
+
+interface ApiEnvelope {
+ success: boolean;
+ data: T;
+ error?: string;
+}
+
+interface InstanceListResponse {
+ instances: InstanceRecord[];
+ total: number;
+ page: number;
+ limit: number;
+}
+
+interface PasswordExternalAccessResult {
+ access: {
+ id: number;
+ instance_id: number;
+ enabled: boolean;
+ auth_mode: string;
+ };
+ password: string;
+ share_url?: string;
+}
+
+function modeOf(instance: InstanceRecord): InstanceMode {
+ if (instance.instance_mode === "lite" || instance.instance_mode === "pro") {
+ return instance.instance_mode;
+ }
+ return instance.runtime_type === "gateway" ? "lite" : "pro";
+}
+
+function activeInstances(instances: InstanceRecord[]) {
+ return instances.filter((instance) => instance.status !== "deleting");
+}
+
+function escapeRegExp(value: string) {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function firstMode(instances: InstanceRecord[], mode: InstanceMode) {
+ return activeInstances(instances).find((instance) => modeOf(instance) === mode);
+}
+
+function runningOpenClawLiteInstances(instances: InstanceRecord[]) {
+ return activeInstances(instances).filter(
+ (instance) =>
+ instance.type === "openclaw" &&
+ modeOf(instance) === "lite" &&
+ instance.status === "running"
+ );
+}
+
+async function apiFromPage(
+ page: Page,
+ path: string,
+ options: { method?: string; data?: unknown } = {}
+): Promise {
+ const result = await page.evaluate(
+ async ({ requestPath, method, data }) => {
+ const accessToken = window.localStorage.getItem("access_token");
+ const headers: Record = {};
+ if (accessToken) {
+ headers.Authorization = `Bearer ${accessToken}`;
+ }
+ if (data !== undefined) {
+ headers["Content-Type"] = "application/json";
+ }
+
+ const response = await fetch(requestPath, {
+ method,
+ headers,
+ body: data === undefined ? undefined : JSON.stringify(data)
+ });
+ const text = await response.text();
+ let payload: ApiEnvelope | null = null;
+ if (text) {
+ payload = JSON.parse(text) as ApiEnvelope;
+ }
+ return { ok: response.ok, status: response.status, payload, text };
+ },
+ {
+ requestPath: path,
+ method: options.method ?? "GET",
+ data: options.data
+ }
+ );
+
+ if (!result.ok || !result.payload?.success) {
+ throw new Error(result.payload?.error || result.text || `request failed with status ${result.status}`);
+ }
+ return result.payload.data as T;
+}
+
+async function adminInstances(page: Page) {
+ await page.goto("/dashboard");
+ const response = await apiFromPage(page, "/api/v1/admin/instances?page=1&limit=1000");
+ return response.instances;
+}
+
+async function userInstances(page: Page) {
+ await page.goto("/dashboard");
+ const response = await apiFromPage(page, "/api/v1/instances?page=1&limit=1000");
+ return response.instances;
+}
+
+async function primeOpenClawGatewayStorage(page: Page, instanceId: number) {
+ await page.goto("/dashboard");
+ await page.evaluate((staleInstanceId) => {
+ for (const key of Object.keys(window.localStorage)) {
+ if (/openclaw|clawmanager\.openclaw/i.test(key)) {
+ window.localStorage.removeItem(key);
+ }
+ }
+
+ const gatewayURL = new URL(`/api/v1/instances/${staleInstanceId}/proxy`, window.location.origin);
+ gatewayURL.protocol = gatewayURL.protocol === "https:" ? "wss:" : "ws:";
+ gatewayURL.search = "";
+ gatewayURL.hash = "";
+ gatewayURL.pathname = gatewayURL.pathname.replace(/\/+$/, "");
+
+ const settings = {
+ gatewayUrl: gatewayURL.toString(),
+ sessionKey: "main",
+ lastActiveSessionKey: "main",
+ theme: "claw",
+ themeMode: "system",
+ chatFocusMode: false,
+ chatShowThinking: true,
+ chatShowToolCalls: true,
+ splitRatio: 0.6,
+ navCollapsed: false,
+ navWidth: 220,
+ navGroupsCollapsed: {},
+ borderRadius: 50,
+ sessionsByGateway: {
+ [gatewayURL.toString()]: {
+ sessionKey: "main",
+ lastActiveSessionKey: "main"
+ }
+ }
+ };
+ const serialized = JSON.stringify(settings);
+ window.localStorage.setItem("openclaw.control.settings.v1", serialized);
+ window.localStorage.setItem(`openclaw.control.settings.v1:${gatewayURL.toString()}`, serialized);
+ window.localStorage.setItem("clawmanager.openclaw.instanceId", String(staleInstanceId));
+ window.localStorage.setItem("clawmanager.openclaw.gatewayUrl", gatewayURL.toString());
+ }, instanceId);
+}
+
+async function expectedGatewayURL(page: Page, instanceId: number) {
+ return page.evaluate((targetInstanceId) => {
+ const gatewayURL = new URL(`/api/v1/instances/${targetInstanceId}/proxy`, window.location.origin);
+ gatewayURL.protocol = gatewayURL.protocol === "https:" ? "wss:" : "ws:";
+ gatewayURL.search = "";
+ gatewayURL.hash = "";
+ gatewayURL.pathname = gatewayURL.pathname.replace(/\/+$/, "");
+ return gatewayURL.toString();
+ }, instanceId);
+}
+
+async function reachConfigurationStep(page: Page, mode: InstanceMode) {
+ await page.goto("/instances/new");
+ await expect(page.getByRole("heading", { name: /create instance/i })).toBeVisible();
+
+ await page.locator("main input#name").nth(1).fill(`e2e-${mode}-mode-check`);
+ await page.getByRole("button", { name: new RegExp(`^${mode === "lite" ? "Lite" : "Pro"}`, "i") }).click();
+ const basicNextButton = page.getByRole("button", { name: /^Next$/i });
+ await expect(basicNextButton).toBeEnabled();
+ await basicNextButton.click();
+
+ await expect(page.getByRole("heading", { name: /select instance type/i })).toBeVisible();
+ const nextButton = page.getByRole("button", { name: /^Next$/i });
+ await expect(nextButton).toBeEnabled();
+ await nextButton.click();
+
+ await expect(page.getByRole("heading", { name: /summary/i })).toBeVisible();
+}
+
+async function visiblePageText(page: Page) {
+ return page.evaluate(() => document.body.innerText);
+}
+
+test.describe("lite/pro instance modes", () => {
+ test("@p0 create wizard exposes the lite/pro mode contract", async ({ page }) => {
+ await test.step("lite derives gateway runtime and skips dedicated resources", async () => {
+ await reachConfigurationStep(page, "lite");
+ const summary = page.locator(".app-panel").filter({
+ has: page.getByRole("heading", { name: /summary/i })
+ });
+
+ await expect(summary.getByText(/^Lite$/)).toBeVisible();
+ await expect(summary.getByText(/^Gateway$/)).toBeVisible();
+ await expect(page.getByRole("heading", { name: /quick configuration/i })).toHaveCount(0);
+ await expect(page.getByRole("button", { name: /enable gpu/i })).toHaveCount(0);
+ await expect(summary.getByText(/^CPU$/)).toHaveCount(0);
+ await expect(summary.getByText(/^Memory$/)).toHaveCount(0);
+ await expect(summary.getByText(/^Storage$/)).toHaveCount(0);
+ await expect(summary.getByText(/^GPU$/)).toHaveCount(0);
+ });
+
+ await test.step("pro derives desktop runtime and shows dedicated resources", async () => {
+ await reachConfigurationStep(page, "pro");
+ const summary = page.locator(".app-panel").filter({
+ has: page.getByRole("heading", { name: /summary/i })
+ });
+
+ await expect(summary.getByText(/^Pro$/)).toBeVisible();
+ await expect(summary.getByText(/^Desktop$/)).toBeVisible();
+ await expect(page.getByRole("heading", { name: /quick configuration/i })).toBeVisible();
+ await expect(page.getByRole("button", { name: /enable gpu/i })).toBeVisible();
+ await expect(summary.getByText(/^CPU$/)).toBeVisible();
+ await expect(summary.getByText(/^Memory$/)).toBeVisible();
+ await expect(summary.getByText(/^Storage$/)).toBeVisible();
+ await expect(summary.getByText(/^GPU$/)).toBeVisible();
+ });
+ });
+
+ test("@p0 lite detail keeps gateway workspace layout", async ({ page }) => {
+ const instances = await adminInstances(page);
+ const lite = firstMode(instances, "lite");
+ if (!lite) {
+ test.skip(true, "No lite/gateway instance exists in this target environment.");
+ return;
+ }
+
+ await page.goto(`/instances/${lite.id}`);
+ await expect(page.getByRole("heading", { name: lite.name }).first()).toBeVisible();
+ await expect.poll(() => visiblePageText(page)).toContain("Mode Lite");
+ await expect.poll(() => visiblePageText(page)).toContain("Runtime gateway");
+ await page.getByRole("button", { name: /share link/i }).click();
+ await expect(page.locator('[data-panel="share-link-popover"]').last()).toBeVisible();
+ await expect(page.getByRole("button", { name: /create password/i })).toBeVisible();
+
+ await expect(page.getByRole("heading", { name: /runtime overview/i })).toHaveCount(0);
+ await expect(page.getByRole("heading", { name: /runtime events/i })).toHaveCount(0);
+ await expect(page.getByRole("heading", { name: /instance skills/i })).toHaveCount(0);
+ });
+
+ test("@p0 pro detail keeps desktop management layout", async ({ page }) => {
+ const instances = await adminInstances(page);
+ const pro = firstMode(instances, "pro");
+ if (!pro) {
+ test.skip(true, "No pro/desktop instance exists in this target environment.");
+ return;
+ }
+
+ await page.goto(`/instances/${pro.id}`);
+ await expect(page.getByRole("heading", { name: pro.name }).first()).toBeVisible();
+ await expect.poll(() => visiblePageText(page)).toContain("Mode Pro");
+ await expect.poll(() => visiblePageText(page)).toContain("Runtime desktop");
+ await page.getByRole("button", { name: /share link/i }).click();
+ await expect(page.locator('[data-panel="share-link-popover"]').last()).toBeVisible();
+ await expect(page.getByRole("button", { name: /create password/i })).toBeVisible();
+
+ await expect(page.getByRole("heading", { name: /runtime overview/i })).toBeVisible();
+ await expect(page.getByRole("heading", { name: /runtime events/i })).toBeVisible();
+ await expect(page.getByRole("heading", { name: /instance skills/i })).toBeVisible();
+ const proDetailText = await visiblePageText(page);
+ expect(proDetailText.indexOf("Instance Skills")).toBeLessThan(proDetailText.indexOf("Runtime Overview"));
+ expect(proDetailText).not.toContain("Resource Monitor");
+ expect(proDetailText).not.toContain("Runtime Status");
+
+ const workspace = await apiFromPage<{ entries: Array<{ path: string }> }>(
+ page,
+ `/api/v1/instances/${pro.id}/workspace/files?path=`
+ );
+ expect(workspace.entries.length).toBeGreaterThan(0);
+ expect(workspace.entries.some((entry) => [".config", ".openclaw", "Desktop"].includes(entry.path))).toBeTruthy();
+ });
+
+ test("@p0 admin instances page surfaces mode and backend management controls", async ({ page }) => {
+ const instances = await adminInstances(page);
+ const lite = firstMode(instances, "lite");
+ const pro = firstMode(instances, "pro");
+
+ await page.goto("/admin/instances");
+ await expect(page.getByRole("heading", { name: /global instances/i })).toBeVisible();
+ await expect.poll(() => visiblePageText(page)).toContain("Gateway runtime");
+ await expect.poll(() => visiblePageText(page)).toContain("Desktop deployment");
+
+ const filters = page.locator("main select");
+ const modeFilter = filters.nth(6);
+ const runtimeFilter = filters.nth(7);
+ await expect(modeFilter).toContainText("Lite");
+ await expect(modeFilter).toContainText("Pro");
+ await expect(runtimeFilter).toContainText("Gateway");
+ await expect(runtimeFilter).toContainText("Desktop");
+
+ if (lite) {
+ await modeFilter.selectOption("lite");
+ await expect.poll(() => visiblePageText(page)).toContain(lite.name);
+ await expect.poll(() => visiblePageText(page)).toContain("Gateway binding");
+ await expect.poll(() => visiblePageText(page)).toContain("Gateway");
+ }
+
+ if (pro) {
+ await modeFilter.selectOption("pro");
+ await expect.poll(() => visiblePageText(page)).toContain(pro.name);
+ await expect.poll(() => visiblePageText(page)).toContain("Deployment");
+ await expect.poll(() => visiblePageText(page)).toContain("Desktop");
+ }
+ });
+
+ test("@p0 portal refreshes OpenClaw Lite gateway settings before embedding", async ({ page }) => {
+ const instances = await userInstances(page);
+ const liteInstances = runningOpenClawLiteInstances(instances);
+ if (liteInstances.length < 2) {
+ test.skip(true, "Need at least two running OpenClaw Lite instances for stale gateway coverage.");
+ return;
+ }
+
+ const [target, stale] = liteInstances;
+ await primeOpenClawGatewayStorage(page, stale.id);
+ await page.goto("/portal");
+ await page.locator("button").filter({ hasText: target.name }).first().dispatchEvent("click");
+
+ const gatewayURL = await expectedGatewayURL(page, target.id);
+ await expect
+ .poll(() => page.evaluate(() => window.localStorage.getItem("clawmanager.openclaw.instanceId")))
+ .toBe(String(target.id));
+ await expect
+ .poll(() => page.evaluate(() => window.localStorage.getItem("clawmanager.openclaw.gatewayUrl")))
+ .toBe(gatewayURL);
+
+ const settings = await page.evaluate(() => window.localStorage.getItem("openclaw.control.settings.v1"));
+ expect(settings).toBeTruthy();
+ expect(JSON.parse(settings!).gatewayUrl).toBe(gatewayURL);
+ });
+
+ test("@p1 password share link opens a password gate", async ({ page }) => {
+ const instances = await adminInstances(page);
+ const target = activeInstances(instances).find((instance) => instance.runtime_type !== "shell");
+ if (!target) {
+ test.skip(true, "No non-shell instance exists for share link coverage.");
+ return;
+ }
+
+ let passwordCreated = false;
+ try {
+ const result = await apiFromPage(
+ page,
+ `/api/v1/instances/${target.id}/external-access/password`,
+ {
+ method: "POST",
+ data: {
+ expires_mode: "preset",
+ expires_preset: "1h"
+ }
+ }
+ );
+ passwordCreated = true;
+
+ expect(result.password).toMatch(/^pwd_/);
+ expect(result.share_url).toBeTruthy();
+ expect(result.share_url).toMatch(/^\/s\/[^/?#]+\/$/);
+ expect(result.share_url).not.toContain("token=");
+ expect(result.share_url).not.toContain("/api/v1/");
+ expect(result.share_url).not.toContain("/proxy");
+
+ await page.goto(`/instances/${target.id}`);
+ await page.reload({ waitUntil: "domcontentloaded" });
+ await expect(page.locator('button[data-share-auth="password"]', { hasText: /share link/i }).last()).toBeVisible();
+ await page.getByRole("button", { name: /share link/i }).click();
+ const sharePanel = page.locator('[data-panel="share-link-popover"]').last();
+ const shareHeader = sharePanel.locator(".mb-3").first();
+ await expect(shareHeader).not.toContainText("Password");
+ await expect(shareHeader).not.toContainText(result.password.slice(0, 12));
+ await expect(sharePanel.getByLabel(/share link url/i)).toHaveValue(
+ new RegExp(`${escapeRegExp(result.share_url!)}$`)
+ );
+ await expect(sharePanel).not.toContainText("Password is shown only");
+ await expect(sharePanel).not.toContainText("created before link recovery");
+ await expect(sharePanel.getByRole("button", { name: /copy share link/i })).toBeVisible();
+ await expect(sharePanel.getByRole("button", { name: /copy password/i })).toBeVisible();
+
+ const passwordInput = sharePanel.getByLabel(/share link password/i);
+ await expect(passwordInput).toHaveValue(result.password);
+ await expect(passwordInput).toHaveAttribute("type", "password");
+ await sharePanel.getByRole("button", { name: /show password/i }).click();
+ await expect(passwordInput).toHaveAttribute("type", "text");
+ await expect(sharePanel.getByRole("button", { name: /hide password/i })).toBeVisible();
+
+ await page.goto(result.share_url!);
+ await expect(page.getByRole("heading", { name: /share link password/i })).toBeVisible();
+ await expect(page.locator('input[name="password"]')).toBeVisible();
+ await expect(page.getByRole("button", { name: /open|continue/i })).toBeVisible();
+ } finally {
+ if (passwordCreated) {
+ await page.goto("/dashboard");
+ await apiFromPage(page, `/api/v1/instances/${target.id}/external-access`, {
+ method: "DELETE"
+ });
+ }
+ }
+ });
+});
diff --git a/e2e/tests/smoke/login.spec.ts b/e2e/tests/smoke/login.spec.ts
new file mode 100644
index 0000000..a624f1f
--- /dev/null
+++ b/e2e/tests/smoke/login.spec.ts
@@ -0,0 +1,34 @@
+import { LoginPage } from "../../pages/LoginPage.js";
+import { test, expect } from "../../fixtures/test.js";
+import { users } from "../../fixtures/users.js";
+
+test.use({ storageState: undefined });
+
+test("@p0 login page renders", async ({ page }) => {
+ const loginPage = new LoginPage(page);
+
+ await loginPage.goto();
+ await loginPage.expectVisible();
+});
+
+test("@p0 admin can log in", async ({ page }) => {
+ const loginPage = new LoginPage(page);
+
+ await loginPage.goto();
+ await loginPage.login(users.admin.username, users.admin.password);
+
+ await expect
+ .poll(() => page.evaluate(() => window.localStorage.getItem("access_token")))
+ .toBeTruthy();
+});
+
+test("@p0 failed login shows an error", async ({ page }) => {
+ const loginPage = new LoginPage(page);
+
+ await loginPage.goto();
+ await loginPage.login(users.admin.username, "wrong-password");
+
+ await expect(page.getByText(/invalid username or password|login failed/i)).toBeVisible();
+ await expect(page).toHaveURL(/\/login$/);
+});
+
diff --git a/e2e/tests/smoke/navigation.spec.ts b/e2e/tests/smoke/navigation.spec.ts
new file mode 100644
index 0000000..637607b
--- /dev/null
+++ b/e2e/tests/smoke/navigation.spec.ts
@@ -0,0 +1,48 @@
+import { test, expect } from "../../fixtures/test.js";
+import { users } from "../../fixtures/users.js";
+
+test.describe("authenticated admin navigation", () => {
+ test.use({ storageState: users.admin.storageState });
+
+ test("@p0 authenticated admin reaches workspace dashboard", async ({ page }) => {
+ await page.goto("/dashboard");
+
+ await expect(page.getByRole("heading", { name: /workspace/i })).toBeVisible();
+ });
+
+ test("@p0 authenticated admin reaches admin console", async ({ page }) => {
+ await page.goto("/admin");
+
+ await expect(page.getByRole("heading", { name: /console/i })).toBeVisible();
+ });
+
+ test("@p0 authenticated admin can reach instances, settings, and admin entry routes", async ({ page }) => {
+ await page.goto("/instances");
+ await expect(page.getByRole("heading", { name: /my instances/i })).toBeVisible();
+
+ await page.goto("/settings");
+ await expect(page.getByRole("heading", { name: /settings/i })).toBeVisible();
+ await expect(page.getByRole("heading", { name: /change password/i })).toBeVisible();
+
+ await page.goto("/admin");
+ await expect(page.getByRole("link", { name: /^runtime$/i }).first()).toBeVisible();
+ await expect(page.getByRole("link", { name: /^settings$/i }).first()).toBeVisible();
+
+ await page.goto("/admin/runtime-pods");
+ await expect(page.getByRole("heading", { name: /^runtime$/i })).toBeVisible();
+
+ await page.goto("/admin/settings");
+ await expect(page.getByRole("heading", { name: /system settings/i })).toBeVisible();
+ });
+});
+
+test.describe("unauthenticated navigation", () => {
+ test.use({ storageState: undefined });
+
+ test("@p0 unauthenticated users are redirected to login", async ({ page }) => {
+ await page.goto("/instances");
+
+ await expect(page).toHaveURL(/\/login$/);
+ await expect(page.getByRole("heading", { name: /sign in to clawmanager/i })).toBeVisible();
+ });
+});
diff --git a/e2e/tests/teams/team-lite-mode.spec.ts b/e2e/tests/teams/team-lite-mode.spec.ts
new file mode 100644
index 0000000..772a26d
--- /dev/null
+++ b/e2e/tests/teams/team-lite-mode.spec.ts
@@ -0,0 +1,79 @@
+import { expect, test } from "../../fixtures/test.js";
+import {
+ createTeam,
+ deleteTeam,
+ getTeam,
+ listInstances,
+ login
+} from "../../fixtures/apiClient.js";
+import { users } from "../../fixtures/users.js";
+
+test.describe("Team lite member mode", () => {
+ test("@p0 creates Team members as Lite gateway instances", async ({ request }) => {
+ const tokens = await login(request, users.admin);
+ const teamName = `e2e-lite-team-${Date.now().toString(36)}`;
+ let teamId: number | undefined;
+
+ try {
+ const created = await createTeam(request, tokens.access_token, {
+ name: teamName,
+ description: "E2E coverage for Team Lite member creation",
+ communication_mode: "leader_mediated",
+ shared_storage_gb: 1,
+ members: [
+ {
+ member_id: "leader",
+ name: "lite-leader",
+ role: "leader",
+ mode: "lite",
+ instance_mode: "lite",
+ runtime_type: "openclaw",
+ cpu_cores: 0.1,
+ memory_gb: 1,
+ disk_gb: 10,
+ is_leader: true
+ },
+ {
+ member_id: "worker",
+ name: "lite-worker",
+ role: "developer",
+ mode: "lite",
+ instance_mode: "lite",
+ runtime_type: "openclaw",
+ cpu_cores: 0.1,
+ memory_gb: 1,
+ disk_gb: 10
+ }
+ ]
+ });
+ teamId = created.team.id;
+
+ expect(created.team.name).toBe(teamName);
+ expect(created.leader_member_id).toBe("leader");
+ expect(created.members).toHaveLength(2);
+ expect(created.members.every((member) => member.instance_mode === "lite")).toBeTruthy();
+ expect(created.members.every((member) => member.runtime_type === "openclaw")).toBeTruthy();
+ expect(created.members.every((member) => typeof member.instance_id === "number")).toBeTruthy();
+
+ const details = await getTeam(request, tokens.access_token, teamId);
+ expect(details.team.status).toBe("running");
+ expect(details.members.map((member) => member.member_key).sort()).toEqual(["leader", "worker"]);
+ expect(details.members.every((member) => member.instance_mode === "lite")).toBeTruthy();
+
+ const instanceIds = new Set(
+ details.members
+ .map((member) => member.instance_id)
+ .filter((id): id is number => typeof id === "number")
+ );
+ const instances = await listInstances(request, tokens.access_token, { admin: true, limit: 1000 });
+ const memberInstances = instances.instances.filter((instance) => instanceIds.has(instance.id));
+ expect(memberInstances).toHaveLength(2);
+ expect(memberInstances.every((instance) => instance.instance_mode === "lite")).toBeTruthy();
+ expect(memberInstances.every((instance) => instance.runtime_type === "gateway")).toBeTruthy();
+ } finally {
+ if (teamId !== undefined) {
+ await deleteTeam(request, tokens.access_token, teamId);
+ }
+ }
+ });
+});
diff --git a/e2e/tsconfig.json b/e2e/tsconfig.json
new file mode 100644
index 0000000..4236e38
--- /dev/null
+++ b/e2e/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "strict": true,
+ "types": ["node", "@playwright/test"],
+ "esModuleInterop": true,
+ "forceConsistentCasingInFileNames": true,
+ "skipLibCheck": true,
+ "resolveJsonModule": true,
+ "noEmit": true
+ },
+ "include": ["**/*.ts"]
+}
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index f7d6fe7..2eb1659 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -13,6 +13,7 @@
"@xterm/addon-unicode11": "^0.9.0",
"@xterm/xterm": "^6.0.0",
"axios": "^1.13.6",
+ "lucide-react": "^1.17.0",
"react": "^19.2.4",
"react-dom": "^19.2.4",
"react-router-dom": "^7.13.1",
@@ -3024,6 +3025,15 @@
"yallist": "^3.0.2"
}
},
+ "node_modules/lucide-react": {
+ "version": "1.17.0",
+ "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.17.0.tgz",
+ "integrity": "sha512-9FA9evdox/JQL5PT57fdA1x/yg8T7knJ98+zjTL3UfKza6pflQUUh3XtaQIHKvnsJw1lmsEyHVlt5jchYxOQ5w==",
+ "license": "ISC",
+ "peerDependencies": {
+ "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+ }
+ },
"node_modules/math-intrinsics": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index c90b4ae..1ad39df 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -15,6 +15,7 @@
"@xterm/addon-unicode11": "^0.9.0",
"@xterm/xterm": "^6.0.0",
"axios": "^1.13.6",
+ "lucide-react": "^1.17.0",
"react": "^19.2.4",
"react-dom": "^19.2.4",
"react-router-dom": "^7.13.1",
diff --git a/frontend/public/lobster_logo.png b/frontend/public/lobster_logo.png
new file mode 100644
index 0000000..7592055
Binary files /dev/null and b/frontend/public/lobster_logo.png differ
diff --git a/frontend/scripts/create-instance-page-mode.test.mjs b/frontend/scripts/create-instance-page-mode.test.mjs
new file mode 100644
index 0000000..cea99eb
--- /dev/null
+++ b/frontend/scripts/create-instance-page-mode.test.mjs
@@ -0,0 +1,74 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const sourcePath = path.resolve(
+ scriptDir,
+ "../src/pages/instances/CreateInstancePage.tsx",
+);
+const source = readFileSync(sourcePath, "utf8");
+
+function sectionBetween(startMarker, endMarker) {
+ const start = source.indexOf(startMarker);
+ const end = source.indexOf(endMarker);
+ if (start === -1 || end === -1 || end <= start) {
+ throw new Error(`Unable to locate section: ${startMarker}`);
+ }
+ return source.slice(start, end);
+}
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+const stepOne = sectionBetween(
+ "{/* Step 1: Basic Information */}",
+ "{/* Step 2: Select Type */}",
+);
+const stepTwo = sectionBetween(
+ "{/* Step 2: Select Type */}",
+ "{/* Step 3: Configuration */}",
+);
+const stepThree = source.slice(source.indexOf("{/* Step 3: Configuration */}"));
+
+assert(
+ /id:\s*"lite"/.test(source) && /id:\s*"pro"/.test(source),
+ "Create instance page must define Lite and Pro mode options.",
+);
+assert(
+ stepOne.includes("renderInstanceModeSelector()"),
+ "Lite/Pro selector must be visible in step 1.",
+);
+assert(
+ !stepTwo.includes("renderInstanceModeSelector()"),
+ "Lite/Pro selector should not be hidden behind step 2.",
+);
+assert(
+ source.includes('const usesDedicatedResources = selectedMode === "pro";'),
+ "Create page must distinguish Pro-only dedicated resource controls.",
+);
+assert(
+ source.includes('const showRuntimeImageSelector = selectedMode === "pro";'),
+ "Runtime image selector visibility must be controlled by Pro mode only.",
+);
+assert(
+ stepTwo.includes("{showRuntimeImageSelector && ("),
+ "Step 2 runtime image selector must be hidden for Lite mode.",
+);
+assert(
+ stepThree.includes("{usesDedicatedResources && ("),
+ "Step 3 resource controls must be hidden for Lite mode.",
+);
+assert(
+ stepThree.includes("{showRuntimeImageSelector && ("),
+ "Step 3 summary must hide runtime image details for Lite mode.",
+);
+assert(
+ source.includes("...(usesDedicatedResources"),
+ "Quota validation must include CPU/memory/storage/GPU only for Pro mode.",
+);
+
+console.log("Create instance mode selector placement is valid.");
diff --git a/frontend/scripts/instance-detail-pro-layout.test.mjs b/frontend/scripts/instance-detail-pro-layout.test.mjs
new file mode 100644
index 0000000..ef9e5f3
--- /dev/null
+++ b/frontend/scripts/instance-detail-pro-layout.test.mjs
@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const detailSource = readFileSync(
+ path.resolve(scriptDir, "../src/pages/instances/InstanceDetailPage.tsx"),
+ "utf8",
+);
+const frameSource = readFileSync(
+ path.resolve(scriptDir, "../src/components/InstanceServiceFrame.tsx"),
+ "utf8",
+);
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ detailSource.includes("isDedicatedInstance") &&
+ detailSource.includes('instance.instance_mode === "pro"') &&
+ detailSource.includes('instance.runtime_type !== "gateway"'),
+ "Instance detail page must branch pro/desktop instances away from the lite workspace layout.",
+);
+
+for (const label of ["Runtime Overview", "Runtime Events", "Instance Skills"]) {
+ assert(detailSource.includes(label), `Pro instance detail section missing: ${label}`);
+}
+
+for (const api of ["getRuntimeDetails", "listInstanceSkills", "attachSkillToInstance", "removeSkillFromInstance"]) {
+ assert(detailSource.includes(api), `Pro instance detail page must use ${api}.`);
+}
+
+assert(
+ detailSource.includes("renderLiteWorkspace") && detailSource.includes("renderProWorkspace"),
+ "Instance detail page must keep separate lite and pro render paths.",
+);
+
+function sliceBetween(source, startMarker, endMarker) {
+ const start = source.indexOf(startMarker);
+ assert(start >= 0, `Missing marker: ${startMarker}`);
+ const end = source.indexOf(endMarker, start);
+ assert(end > start, `Missing end marker after: ${startMarker}`);
+ return source.slice(start, end);
+}
+
+const proRender = sliceBetween(
+ detailSource,
+ "const renderProWorkspace = () => (",
+ "\n return (",
+);
+
+assert(
+ proRender.includes("shareLinkControl"),
+ "Pro instance detail must place Share Link with the primary instance action buttons.",
+);
+
+assert(
+ !detailSource.includes("externalAccessSection") && !detailSource.includes("externalAccessCompact"),
+ "Instance detail must not render the old full-width or inline external access controls.",
+);
+
+assert(
+ detailSource.includes('data-panel="share-link-popover"') &&
+ detailSource.includes("Share link expiration") &&
+ detailSource.includes("Create Password"),
+ "Share link expiration and password controls must live inside the Share Link popover.",
+);
+
+assert(
+ proRender.includes('data-section="runtime-overview"') &&
+ proRender.indexOf("Instance Skills") < proRender.indexOf("Runtime Overview"),
+ "Instance Skills must render before the compact Runtime Overview card.",
+);
+
+assert(
+ !proRender.includes("Resource Monitor") && !proRender.includes("Runtime Status"),
+ "Runtime Overview must use a compact summary instead of large nested Resource Monitor and Runtime Status sections.",
+);
+
+assert(
+ proRender.includes('initialPath="/config"'),
+ "Pro instance workspace must open at /config.",
+);
+
+assert(
+ proRender.includes("pro-desktop-workspace"),
+ "Pro instance workspace must be placed in the desktop workspace area.",
+);
+
+assert(
+ !proRender.includes("h-[560px]") &&
+ (proRender.includes("aspect-video") || proRender.includes("aspect-[16/9]")),
+ "Pro desktop frame must use a stable 16:9 desktop ratio instead of the old fixed height.",
+);
+
+assert(
+ proRender.indexOf("Runtime Events") > proRender.indexOf("Runtime Overview"),
+ "Runtime Events must be lower priority and render after Instance Skills.",
+);
+
+assert(
+ frameSource.includes("requestFullscreen") &&
+ frameSource.includes("Maximize2") &&
+ frameSource.includes("Minimize2"),
+ "Instance service frame must expose a fullscreen control.",
+);
+
+console.log("Instance detail pro layout contract is valid.");
diff --git a/frontend/scripts/instance-external-access.test.mjs b/frontend/scripts/instance-external-access.test.mjs
new file mode 100644
index 0000000..8bedbca
--- /dev/null
+++ b/frontend/scripts/instance-external-access.test.mjs
@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const detailSource = readFileSync(
+ path.resolve(scriptDir, "../src/pages/instances/InstanceDetailPage.tsx"),
+ "utf8",
+);
+const serviceSource = readFileSync(
+ path.resolve(scriptDir, "../src/services/instanceService.ts"),
+ "utf8",
+);
+const typeSource = readFileSync(
+ path.resolve(scriptDir, "../src/types/instance.ts"),
+ "utf8",
+);
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+for (const label of ["1 hour", "24 hours", "7 days", "30 days", "Custom", "Permanent"]) {
+ assert(detailSource.includes(label), `External access expiration option missing: ${label}`);
+}
+
+assert(
+ detailSource.includes('useState("preset")') &&
+ detailSource.includes('useState("24h")'),
+ "External access UI must default to a 24 hour preset.",
+);
+assert(
+ serviceSource.includes("ExternalAccessRequest") &&
+ serviceSource.includes("external-access/share-link") &&
+ serviceSource.includes("external-access/password"),
+ "Instance service must send expiration payloads to share link and password endpoints.",
+);
+assert(
+ detailSource.includes("Share Link") &&
+ detailSource.includes("Password") &&
+ !detailSource.includes("Public Link") &&
+ !detailSource.includes("API Key"),
+ "Instance external access UI must use Share Link and Password labels.",
+);
+assert(
+ !serviceSource.includes("external-access/public-link") &&
+ !serviceSource.includes("external-access/api-key"),
+ "Instance service must not call legacy public-link or api-key endpoints.",
+);
+assert(
+ !typeSource.includes("public_slug:") && !typeSource.includes("token?:"),
+ "Frontend external access types must not expose legacy long-link slug or token fields.",
+);
+
+console.log("Instance external access short-link UI contract is valid.");
diff --git a/frontend/scripts/instance-list-websocket.test.mjs b/frontend/scripts/instance-list-websocket.test.mjs
new file mode 100644
index 0000000..a45e423
--- /dev/null
+++ b/frontend/scripts/instance-list-websocket.test.mjs
@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const listSource = readFileSync(
+ path.resolve(scriptDir, "../src/pages/instances/InstanceListPage.tsx"),
+ "utf8",
+);
+const detailSource = readFileSync(
+ path.resolve(scriptDir, "../src/pages/instances/InstanceDetailPage.tsx"),
+ "utf8",
+);
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ !listSource.includes("useInstanceStatusWebSocket") &&
+ !listSource.includes("InstanceStatusUpdate"),
+ "Instance list must not keep a long-lived instance status WebSocket connection.",
+);
+
+assert(
+ listSource.includes("window.setInterval") &&
+ listSource.includes('instance.status === "creating"') &&
+ listSource.includes('instance.status === "deleting"'),
+ "Instance list must keep transition-state polling after removing WebSocket updates.",
+);
+
+assert(
+ detailSource.includes("useInstanceStatusWebSocket"),
+ "Instance detail should keep WebSocket updates for focused real-time status.",
+);
+
+console.log("Instance list WebSocket contract is valid.");
diff --git a/frontend/scripts/instance-portal-mode-layout.test.mjs b/frontend/scripts/instance-portal-mode-layout.test.mjs
new file mode 100644
index 0000000..78f8c91
--- /dev/null
+++ b/frontend/scripts/instance-portal-mode-layout.test.mjs
@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const portalSource = readFileSync(
+ path.resolve(scriptDir, "../src/pages/instances/InstancePortalPage.tsx"),
+ "utf8",
+);
+const desktopAccessHookSource = readFileSync(
+ path.resolve(scriptDir, "../src/hooks/useInstanceDesktopAccess.ts"),
+ "utf8",
+);
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ portalSource.includes("WorkspaceFileManager"),
+ "Portal must reuse the instance detail workspace file manager.",
+);
+
+assert(
+ portalSource.includes('selectedInstance.instance_mode === "pro"'),
+ "Portal must branch rendering by instance_mode so Lite instances are not shown as Pro.",
+);
+
+assert(
+ portalSource.includes('initialPath="/config"'),
+ "Portal Pro workspace file manager must match detail page config-root behavior.",
+);
+
+assert(
+ portalSource.includes('data-portal-mode={isProPortal ? "pro" : "lite"}'),
+ "Portal must expose separate Pro and Lite layout markers.",
+);
+
+assert(
+ portalSource.includes("xl:grid-rows-[minmax(0,1fr)]") &&
+ portalSource.includes("xl:overflow-hidden") &&
+ !portalSource.includes("content-start overflow-y-auto") &&
+ !portalSource.includes("aspect-video"),
+ "Portal Pro desktop layout must stretch to fill the available height without leaving a lower blank area.",
+);
+
+assert(
+ portalSource.includes("canShowRuntimeOverlay") &&
+ portalSource.includes("isProPortal"),
+ "Portal runtime controls must be limited to Pro layout.",
+);
+
+assert(
+ !portalSource.includes("__openclaw__/canvas"),
+ "Portal Pro desktop instances must use the backend proxy entry instead of the OpenClaw gateway canvas route.",
+);
+
+assert(
+ portalSource.includes("portalEmbedUrl") &&
+ portalSource.includes("portalEmbedUrlForInstance") &&
+ portalSource.includes("preparedPortalFrame.embedUrl === portalEmbedUrl") &&
+ portalSource.includes("src={portalFrameSrc}"),
+ "Portal iframe must use a mode-aware embed URL instead of the raw access URL.",
+);
+
+assert(
+ portalSource.includes("instanceIdFromProxyUrl") &&
+ portalSource.includes("embedUrlInstanceId !== instance.id"),
+ "Portal iframe must not reuse an access URL from a previously selected instance.",
+);
+
+assert(
+ portalSource.includes("setShouldConnect(false)") &&
+ portalSource.includes("instance.id !== selectedId"),
+ "Portal must reset the connection intent before switching to another instance.",
+);
+
+assert(
+ portalSource.includes("pendingConnectInstanceIdRef") &&
+ portalSource.includes("pendingConnectInstanceIdRef.current === nextInstanceId") &&
+ portalSource.includes("shouldConnect && portalEmbedUrl"),
+ "Portal access generation must target the currently selected instance after switching.",
+);
+
+assert(
+ portalSource.includes('selectedInstanceStatus !== "running"') &&
+ portalSource.includes("requestAccess();"),
+ "Portal must auto-connect running instances when switching in the portal.",
+);
+
+assert(
+ /modeLabel\(\s*instance\.instance_mode\s*\)/.test(portalSource) &&
+ /modeClass\(\s*instance\.instance_mode\s*,?\s*\)/.test(portalSource),
+ "Portal left instance list must display the Lite/Pro instance type.",
+);
+
+assert(
+ desktopAccessHookSource.includes("refreshAccess({ forceReload: true })"),
+ "Desktop access hook must force a fresh access URL when connecting a selected instance.",
+);
+
+console.log("Instance portal mode layout contract is valid.");
diff --git a/frontend/scripts/runtime-pods-page-contract.test.mjs b/frontend/scripts/runtime-pods-page-contract.test.mjs
new file mode 100644
index 0000000..07f04a0
--- /dev/null
+++ b/frontend/scripts/runtime-pods-page-contract.test.mjs
@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const layoutPath = path.resolve(scriptDir, "../src/components/AdminLayout.tsx");
+const pagePath = path.resolve(scriptDir, "../src/pages/admin/RuntimePodsPage.tsx");
+const i18nPath = path.resolve(scriptDir, "../src/lib/i18n.ts");
+
+const layoutSource = readFileSync(layoutPath, "utf8");
+const pageSource = readFileSync(pagePath, "utf8");
+const i18nSource = readFileSync(i18nPath, "utf8");
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ layoutSource.includes("t('nav.runtime')") || layoutSource.includes('t("nav.runtime")'),
+ "Admin sidebar must label the runtime pod page through nav.runtime.",
+);
+assert(
+ !layoutSource.includes("label: 'Runtime Pods'") && !layoutSource.includes('label: "Runtime Pods"'),
+ "Admin sidebar must not hard-code Runtime Pods.",
+);
+assert(
+ pageSource.includes("t('runtimePods.title')") || pageSource.includes('t("runtimePods.title")'),
+ "Runtime pods page title must use runtimePods.title.",
+);
+assert(
+ pageSource.includes("selectRuntimePod(pod)") &&
+ pageSource.includes('role="button"') &&
+ pageSource.includes("onKeyDown={(event) => handleRuntimePodCardKeyDown(event, pod)}"),
+ "Runtime pod cards must be selectable by clicking or using the keyboard.",
+);
+assert(
+ pageSource.includes("event.stopPropagation()"),
+ "Runtime pod card action buttons must not trigger card selection accidentally.",
+);
+assert(
+ i18nSource.includes('runtime: "Runtime"') &&
+ i18nSource.includes('runtime: "运行时"') &&
+ i18nSource.includes('title: "运行时"'),
+ "Runtime page translations must include English and Chinese runtime labels.",
+);
+
+console.log("Runtime pods page source contract is valid.");
diff --git a/frontend/scripts/system-settings-runtime-groups.test.mjs b/frontend/scripts/system-settings-runtime-groups.test.mjs
new file mode 100644
index 0000000..3675980
--- /dev/null
+++ b/frontend/scripts/system-settings-runtime-groups.test.mjs
@@ -0,0 +1,70 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pagePath = path.resolve(
+ scriptDir,
+ "../src/pages/admin/SystemSettingsPage.tsx",
+);
+const servicePath = path.resolve(
+ scriptDir,
+ "../src/services/systemSettingsService.ts",
+);
+const i18nPath = path.resolve(scriptDir, "../src/lib/i18n.ts");
+
+const pageSource = readFileSync(pagePath, "utf8");
+const serviceSource = readFileSync(servicePath, "utf8");
+const i18nSource = readFileSync(i18nPath, "utf8");
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ serviceSource.includes('"desktop" | "gateway"'),
+ "System image settings must expose desktop/gateway runtime types.",
+);
+assert(
+ !serviceSource.includes('"desktop" | "shell"'),
+ "System image settings must not expose shell as the Lite runtime type.",
+);
+assert(
+ pageSource.includes("LITE_RUNTIME_CARDS") &&
+ pageSource.includes("PRO_BASE_RUNTIME_CARDS"),
+ "System settings page must define separate Lite and Pro runtime groups.",
+);
+assert(
+ pageSource.includes("runtime_type: 'gateway'") &&
+ pageSource.includes("runtime_type: 'desktop'"),
+ "System settings page must map Lite to gateway and Pro to desktop.",
+);
+assert(
+ pageSource.includes("ghcr.io/yuan-lab-llm/agentsruntime/openclaw-lite:latest") &&
+ pageSource.includes("ghcr.io/yuan-lab-llm/agentsruntime/hermes-lite:latest"),
+ "System settings page must use the Lite default runtime images.",
+);
+assert(
+ pageSource.includes("addProCustomCard"),
+ "System settings page must keep custom Pro runtime card creation.",
+);
+assert(
+ pageSource.includes("systemSettingsPage.liteRolloutTitle") &&
+ pageSource.includes("systemSettingsPage.proRuntimeTitle") &&
+ i18nSource.includes("Lite runtime rolling upgrade") &&
+ i18nSource.includes("Pro runtime"),
+ "System settings page must render separate rollout, Lite, and Pro sections.",
+);
+assert(
+ pageSource.includes("runtimePoolService.listPods(rolloutRuntimeType)") &&
+ pageSource.includes("rolloutCurrentImage"),
+ "System settings rollout current image must come from live runtime pods, not only saved card settings.",
+);
+assert(
+ !pageSource.includes("RUNTIME_TYPE_OPTIONS"),
+ "System settings page must not expose the legacy Shell/Desktop selector.",
+);
+
+console.log("System settings runtime grouping source contract is valid.");
diff --git a/frontend/scripts/user-portal-entry.test.mjs b/frontend/scripts/user-portal-entry.test.mjs
new file mode 100644
index 0000000..cbc0705
--- /dev/null
+++ b/frontend/scripts/user-portal-entry.test.mjs
@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const layoutSource = readFileSync(
+ path.resolve(scriptDir, "../src/components/UserLayout.tsx"),
+ "utf8",
+);
+const instanceListSource = readFileSync(
+ path.resolve(scriptDir, "../src/pages/instances/InstanceListPage.tsx"),
+ "utf8",
+);
+const routerSource = readFileSync(
+ path.resolve(scriptDir, "../src/router/index.tsx"),
+ "utf8",
+);
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ !layoutSource.includes("path: '/portal'") &&
+ !layoutSource.includes('path: "/portal"'),
+ "User sidebar must not expose Portal as a top-level navigation entry.",
+);
+assert(
+ instanceListSource.includes('to="/portal"'),
+ "Instance list must keep the Portal entry point.",
+);
+assert(
+ routerSource.includes('path="/portal"'),
+ "Portal route must remain available for instance-page entry points.",
+);
+
+console.log("User portal entry placement is valid.");
diff --git a/frontend/scripts/workspace-folder-upload.test.mjs b/frontend/scripts/workspace-folder-upload.test.mjs
new file mode 100644
index 0000000..c964df7
--- /dev/null
+++ b/frontend/scripts/workspace-folder-upload.test.mjs
@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(
+ path.resolve(scriptDir, "../src/components/WorkspaceFileManager.tsx"),
+ "utf8",
+);
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+assert(
+ source.includes("folderUploadInputRef"),
+ "Workspace file manager must include a dedicated folder upload input.",
+);
+
+assert(
+ /
-
-
+
+
+
+
);
}
diff --git a/frontend/src/components/AdminLayout.tsx b/frontend/src/components/AdminLayout.tsx
index ad1d3f5..1f9ced1 100644
--- a/frontend/src/components/AdminLayout.tsx
+++ b/frontend/src/components/AdminLayout.tsx
@@ -1,5 +1,18 @@
import React, { useState } from 'react';
import { Link, useLocation } from 'react-router-dom';
+import {
+ ArrowLeft,
+ Bot,
+ ChevronDown,
+ Gauge,
+ Home,
+ LogOut,
+ Monitor,
+ Server,
+ Settings,
+ Shield,
+ Users,
+} from 'lucide-react';
import { useAuth } from '../contexts/AuthContext';
import { useI18n } from '../contexts/I18nContext';
import LanguageSwitcher from './LanguageSwitcher';
@@ -12,18 +25,40 @@ interface AdminLayoutProps {
interface NavItem {
path: string;
label: string;
- icon: string;
+ icon: React.ComponentType<{ className?: string }>;
matchPaths?: string[];
exact?: boolean;
}
+const shellContainerClass = 'w-full px-3 sm:px-4 lg:px-5 2xl:px-6';
+const appLogoSrc = '/lobster_logo.png';
+
const AdminLayout: React.FC = ({ children, title }) => {
const location = useLocation();
const { user, logout } = useAuth();
const { t } = useI18n();
- const shellContainerClass = 'mx-auto w-full max-w-[1800px] px-4 sm:px-6 lg:px-8 xl:px-10 2xl:px-12';
const [profileExpanded, setProfileExpanded] = useState(false);
+ const navItems: NavItem[] = [
+ { path: '/admin', label: t('nav.adminDashboard'), icon: Home, exact: true },
+ { path: '/admin/users', label: t('nav.users'), icon: Users },
+ { path: '/admin/instances', label: t('nav.instances'), icon: Monitor },
+ { path: '/admin/runtime-pods', label: t('nav.runtime'), icon: Server },
+ {
+ path: '/admin/security',
+ label: t('nav.securityCenter'),
+ icon: Shield,
+ matchPaths: ['/admin/assets', '/admin/skills'],
+ },
+ {
+ path: '/admin/ai-gateway',
+ label: t('nav.aiGateway'),
+ icon: Bot,
+ matchPaths: ['/admin/models', '/admin/ai-audit', '/admin/costs', '/admin/risk-rules'],
+ },
+ { path: '/admin/settings', label: t('nav.settings'), icon: Settings },
+ ];
+
const isActive = (item: NavItem) => {
if (item.exact) {
return location.pathname === item.path;
@@ -37,19 +72,19 @@ const AdminLayout: React.FC = ({ children, title }) => {
window.location.href = '/login';
};
- const navItems: NavItem[] = [
- { path: '/admin', label: t('nav.adminDashboard'), icon: 'M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6', exact: true },
- { path: '/admin/users', label: t('nav.users'), icon: 'M12 4.354a4 4 0 110 5.292M15 21H3v-1a6 6 0 0112 0v1zm0 0h6v-1a6 6 0 00-9-5.197M13 7a4 4 0 11-8 0 4 4 0 018 0z' },
- { path: '/admin/instances', label: t('nav.instances'), icon: 'M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2m-2-4h.01M17 16h.01' },
- { path: '/admin/security', label: t('nav.securityCenter'), icon: 'M12 2l8 4.5v5c0 5.8-3.6 10.8-8 12.5-4.4-1.7-8-6.7-8-12.5v-5L12 2z', matchPaths: ['/admin/assets', '/admin/skills'] },
- {
- path: '/admin/ai-gateway',
- label: t('nav.aiGateway'),
- icon: 'M12 2l8 4.5v5c0 5.8-3.6 10.8-8 12.5-4.4-1.7-8-6.7-8-12.5v-5L12 2zm0 6.5v3m0 4h.01M9 12h6',
- matchPaths: ['/admin/models', '/admin/ai-audit', '/admin/costs', '/admin/risk-rules'],
- },
- { path: '/admin/settings', label: t('nav.settings'), icon: 'M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z M15 12a3 3 0 11-6 0 3 3 0 016 0z' },
- ];
+ const renderNavItem = (item: NavItem) => {
+ const Icon = item.icon;
+ return (
+
+ = ({ children, title }) => {
-
+
- {t('app.name')}
+ {t('app.name')}
-
+
{title}
-
+ {title}
-
- {children}
-
+ {children}
-