feat: 支持自托管的 remote-control-server (#214)

* feat: 支持自托管的 remote-control-server (#214)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

packages/remote-control-server/.gitignore

@@ -0,0 +1 @@
+data

packages/remote-control-server/Dockerfile

@@ -0,0 +1,32 @@
+# ---- Stage 1: Install deps + build ----
+FROM oven/bun:1 AS builder
+WORKDIR /app
+
+ARG VERSION=0.1.0
+
+COPY packages/remote-control-server/package.json ./package.json
+RUN bun install
+
+COPY packages/remote-control-server/src ./src
+RUN bun build src/index.ts --outfile=dist/server.js --target=bun \
+    --define "process.env.RCS_VERSION=\"${VERSION}\""
+
+# ---- Stage 2: Runtime ----
+FROM oven/bun:1-slim AS runtime
+
+ARG VERSION=0.1.0
+ENV RCS_VERSION=${VERSION}
+
+WORKDIR /app
+
+COPY --from=builder /app/dist/server.js ./dist/server.js
+COPY packages/remote-control-server/web ./web
+
+VOLUME /app/data
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD bun run -e "fetch('http://localhost:3000/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
+
+CMD ["bun", "run", "dist/server.js"]

packages/remote-control-server/README.md

@@ -0,0 +1,167 @@
+# Remote Control Server (RCS)
+
+Remote Control Server 是 Claude Code 的远程控制后端，允许你通过浏览器 Web UI 远程监控和操作 Claude Code 会话。
+
+## 功能
+
+- **会话管理** — 创建、监控、归档 Claude Code 会话
+- **实时消息流** — WebSocket / SSE 双向传输，实时查看对话和工具调用
+- **权限审批** — 在 Web UI 中审批 Claude Code 的工具权限请求
+- **多环境管理** — 注册多个运行环境，支持心跳和断线重连
+- **认证安全** — API Key + JWT 双层认证
+
+## 快速开始
+
+### Docker 部署（推荐）
+
+```bash
+docker run -d \
+  --name rcs \
+  -p 3000:3000 \
+  -e RCS_API_KEYS=your-api-key-here \
+  -v rcs-data:/app/data \
+  ghcr.io/claude-code-best/remote-control-server:latest
+```
+
+## 环境变量
+
+### 服务器配置
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `RCS_PORT` | `3000` | 监听端口 |
+| `RCS_HOST` | `0.0.0.0` | 监听地址 |
+| `RCS_API_KEYS` | _(空)_ | API 密钥列表，逗号分隔。客户端和 Worker 连接时需要提供 |
+| `RCS_BASE_URL` | _(自动)_ | 外部访问地址，例如 `https://rcs.example.com`。用于生成 WebSocket 连接 URL |
+| `RCS_VERSION` | `0.1.0` | 服务版本号，显示在 `/health` 响应中 |
+
+### 超时与心跳
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `RCS_POLL_TIMEOUT` | `8` | V1 轮询超时（秒） |
+| `RCS_HEARTBEAT_INTERVAL` | `20` | 心跳间隔（秒） |
+| `RCS_JWT_EXPIRES_IN` | `3600` | JWT 令牌有效期（秒） |
+| `RCS_DISCONNECT_TIMEOUT` | `300` | 断线判定超时（秒） |
+
+## Claude Code 客户端配置
+
+### 连接到自托管服务器
+
+在 Claude Code 所在环境设置以下变量：
+
+```bash
+# 指向你的 RCS 服务器地址
+export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
+
+# 认证令牌（与 RCS_API_KEYS 中的值对应）
+export CLAUDE_BRIDGE_OAUTH_TOKEN="your-api-key-here"
+```
+
+然后启动远程控制模式：
+
+```bash
+ccb --remote-control
+```
+
+> **注意**：远程控制功能需要启用 `BRIDGE_MODE` feature flag。开发模式下默认启用。
+
+### 环境变量参考
+
+| 变量 | 说明 |
+|------|------|
+| `CLAUDE_BRIDGE_BASE_URL` | RCS 服务器地址，覆盖默认的 Anthropic 云端地址 |
+| `CLAUDE_BRIDGE_OAUTH_TOKEN` | 认证令牌，用于连接 RCS 服务器 |
+| `CLAUDE_BRIDGE_SESSION_INGRESS_URL` | WebSocket 入口地址（默认与 BASE_URL 相同） |
+| `CLAUDE_CODE_REMOTE` | 设为 `1` 时标记为远程执行模式 |
+
+## Docker Compose 示例
+
+```yaml
+version: "3.8"
+services:
+  rcs:
+    build:
+      context: .
+      dockerfile: packages/remote-control-server/Dockerfile
+      args:
+        VERSION: "0.1.0"
+    ports:
+      - "3000:3000"
+    environment:
+      - RCS_API_KEYS=sk-rcs-change-me
+      - RCS_BASE_URL=https://rcs.example.com
+    volumes:
+      - rcs-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  rcs-data:
+```
+
+## 反向代理配置
+
+使用 Nginx 或 Caddy 反向代理时，需要支持 WebSocket 升级：
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name rcs.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 86400s;
+    }
+}
+```
+
+Caddy 配置更简单，自动处理 WebSocket：
+
+```
+rcs.example.com {
+    reverse_proxy localhost:3000
+}
+```
+
+## 架构概览
+
+```
+┌─────────────┐     WebSocket/SSE      ┌──────────────────┐
+│  Claude Code │ ◄──────────────────► │  Remote Control  │
+│  (Bridge CLI)│     HTTP API          │     Server       │
+└─────────────┘                        │                  │
+                                       │  ┌────────────┐  │
+┌─────────────┐     HTTP/SSE          │  │ Event Bus   │  │
+│  Web UI      │ ◄────────────────── │  └────────────┘  │
+│  (/code/*)   │                      │  ┌────────────┐  │
+└─────────────┘                       │  │ In-Memory   │  │
+                                      │  │ Store       │  │
+                                      │  └────────────┘  │
+                                      └──────────────────┘
+```
+
+- **传输层**：WebSocket（V1）和 SSE + HTTP POST（V2）
+- **存储**：纯内存存储（Map），重启后数据清除
+- **认证**：API Key（客户端）+ JWT（Worker）
+- **前端**：原生 JS SPA，通过 `/code/*` 路径访问
+
+## 开发
+
+```bash
+# 安装依赖
+bun install
+
+# 开发模式（热重载）
+bun run dev
+
+# 类型检查
+bun run typecheck
+
+# 运行测试
+bun test packages/remote-control-server/
+```

packages/remote-control-server/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@anthropic/remote-control-server",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "start": "bun run src/index.ts",
+    "build:web": "cd web && bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "hono": "^4.7.0",
+    "uuid": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/vite": "^4.0.0"
+  }
+}

packages/remote-control-server/src/__tests__/auth.test.ts

@@ -0,0 +1,162 @@
+import { describe, test, expect, beforeEach, afterAll, mock, spyOn } from "bun:test";
+
+// Mock config before importing modules that depend on it
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-key-1", "test-key-2"],
+  baseUrl: "",
+  pollTimeout: 8,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { validateApiKey, hashApiKey } from "../auth/api-key";
+import { generateWorkerJwt, verifyWorkerJwt } from "../auth/jwt";
+import { issueToken, resolveToken } from "../auth/token";
+import { storeReset, storeCreateUser } from "../store";
+
+// ---------- api-key ----------
+
+describe("validateApiKey", () => {
+  test("validates a configured API key", () => {
+    expect(validateApiKey("test-key-1")).toBe(true);
+    expect(validateApiKey("test-key-2")).toBe(true);
+  });
+
+  test("rejects unknown key", () => {
+    expect(validateApiKey("unknown-key")).toBe(false);
+  });
+
+  test("rejects undefined", () => {
+    expect(validateApiKey(undefined)).toBe(false);
+  });
+
+  test("rejects empty string", () => {
+    expect(validateApiKey("")).toBe(false);
+  });
+});
+
+describe("hashApiKey", () => {
+  test("produces consistent SHA-256 hex", () => {
+    const hash = hashApiKey("my-key");
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+    expect(hashApiKey("my-key")).toBe(hash);
+  });
+
+  test("different keys produce different hashes", () => {
+    expect(hashApiKey("key-a")).not.toBe(hashApiKey("key-b"));
+  });
+});
+
+// ---------- jwt ----------
+
+describe("JWT", () => {
+  // JWT reads process.env.RCS_API_KEYS directly (not via config)
+  const originalKeys = process.env.RCS_API_KEYS;
+
+  beforeEach(() => {
+    process.env.RCS_API_KEYS = "jwt-test-secret";
+  });
+
+  afterAll(() => {
+    process.env.RCS_API_KEYS = originalKeys;
+  });
+
+  describe("generateWorkerJwt", () => {
+    test("produces a three-part base64url token", () => {
+      const token = generateWorkerJwt("ses_123", 3600);
+      const parts = token.split(".");
+      expect(parts).toHaveLength(3);
+      for (const part of parts) {
+        expect(part).toMatch(/^[A-Za-z0-9_-]+$/);
+      }
+    });
+
+    test("contains correct header", () => {
+      const token = generateWorkerJwt("ses_123", 3600);
+      const header = JSON.parse(atob(token.split(".")[0].replace(/-/g, "+").replace(/_/g, "/")));
+      expect(header.alg).toBe("HS256");
+      expect(header.typ).toBe("JWT");
+    });
+
+    test("throws when no API key configured", () => {
+      delete process.env.RCS_API_KEYS;
+      expect(() => generateWorkerJwt("ses_123", 3600)).toThrow("No API key configured");
+      process.env.RCS_API_KEYS = "jwt-test-secret";
+    });
+  });
+
+  describe("verifyWorkerJwt", () => {
+    test("verifies a valid token", () => {
+      const token = generateWorkerJwt("ses_abc", 3600);
+      const payload = verifyWorkerJwt(token);
+      expect(payload).not.toBeNull();
+      expect(payload!.session_id).toBe("ses_abc");
+      expect(payload!.role).toBe("worker");
+      expect(payload!.iat).toBeGreaterThan(0);
+      expect(payload!.exp).toBeGreaterThan(payload!.iat);
+    });
+
+    test("returns null for expired token", () => {
+      const token = generateWorkerJwt("ses_old", -10);
+      expect(verifyWorkerJwt(token)).toBeNull();
+    });
+
+    test("returns null for malformed token (not 3 parts)", () => {
+      expect(verifyWorkerJwt("a.b")).toBeNull();
+      expect(verifyWorkerJwt("just-a-string")).toBeNull();
+    });
+
+    test("returns null for tampered signature", () => {
+      const token = generateWorkerJwt("ses_123", 3600);
+      const parts = token.split(".");
+      const tampered = `${parts[0]}.${parts[1]}.${parts[2].slice(0, -4)}xxxx`;
+      expect(verifyWorkerJwt(tampered)).toBeNull();
+    });
+
+    test("returns null for wrong signing key", () => {
+      const token = generateWorkerJwt("ses_123", 3600);
+      process.env.RCS_API_KEYS = "wrong-key";
+      expect(verifyWorkerJwt(token)).toBeNull();
+      process.env.RCS_API_KEYS = "jwt-test-secret";
+    });
+  });
+});
+
+// ---------- token ----------
+
+describe("issueToken / resolveToken", () => {
+  beforeEach(() => {
+    storeReset();
+  });
+
+  test("issues and resolves a token", () => {
+    storeCreateUser("alice");
+    const { token, expires_in } = issueToken("alice");
+    expect(token).toMatch(/^rct_\d+_[0-9a-f]+$/);
+    expect(expires_in).toBe(86400);
+    expect(resolveToken(token)).toBe("alice");
+  });
+
+  test("returns null for unknown token", () => {
+    expect(resolveToken("nonexistent")).toBeNull();
+  });
+
+  test("returns null for undefined token", () => {
+    expect(resolveToken(undefined)).toBeNull();
+  });
+
+  test("tokens are unique", () => {
+    storeCreateUser("alice");
+    const t1 = issueToken("alice").token;
+    const t2 = issueToken("alice").token;
+    expect(t1).not.toBe(t2);
+  });
+});

packages/remote-control-server/src/__tests__/disconnect-monitor.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+// Mock config with very short timeout for testing
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 8,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import {
+  storeReset,
+  storeCreateEnvironment,
+  storeUpdateEnvironment,
+  storeCreateSession,
+  storeUpdateSession,
+  storeGetEnvironment,
+  storeGetSession,
+  storeListActiveEnvironments,
+} from "../store";
+
+describe("Disconnect Monitor Logic", () => {
+  beforeEach(() => {
+    storeReset();
+  });
+
+  // Test the logic directly rather than the interval-based monitor
+  // to avoid long-running tests with timers
+
+  test("environment times out when lastPollAt is too old", () => {
+    const env = storeCreateEnvironment({ secret: "s" });
+    const timeoutMs = 300 * 1000; // 5 minutes
+
+    // Simulate lastPollAt being 6 minutes ago
+    const oldDate = new Date(Date.now() - timeoutMs - 60000);
+    storeUpdateEnvironment(env.id, { lastPollAt: oldDate });
+
+    // Check the timeout logic (same as in disconnect-monitor.ts)
+    const now = Date.now();
+    const envs = storeListActiveEnvironments();
+    for (const e of envs) {
+      if (e.lastPollAt && now - e.lastPollAt.getTime() > timeoutMs) {
+        storeUpdateEnvironment(e.id, { status: "disconnected" });
+      }
+    }
+
+    const updated = storeGetEnvironment(env.id);
+    expect(updated?.status).toBe("disconnected");
+  });
+
+  test("environment stays active when lastPollAt is recent", () => {
+    const env = storeCreateEnvironment({ secret: "s" });
+    const timeoutMs = 300 * 1000;
+
+    // lastPollAt is recent (just created)
+    const now = Date.now();
+    const envs = storeListActiveEnvironments();
+    for (const e of envs) {
+      if (e.lastPollAt && now - e.lastPollAt.getTime() > timeoutMs) {
+        storeUpdateEnvironment(e.id, { status: "disconnected" });
+      }
+    }
+
+    const updated = storeGetEnvironment(env.id);
+    expect(updated?.status).toBe("active");
+  });
+
+  test("session becomes inactive when updatedAt is too old", () => {
+    const session = storeCreateSession({ status: "idle" });
+    storeUpdateSession(session.id, { status: "running" });
+    const timeoutMs = 300 * 1000 * 2; // 2x disconnect timeout
+
+    // Simulate updatedAt being older than 2x timeout
+    // We can't directly set updatedAt, but we can verify the logic
+    // by checking that recently updated sessions are not marked inactive
+    const now = Date.now();
+    const rec = storeGetSession(session.id);
+    // Session was just updated, should not be inactive
+    expect(rec?.status).toBe("running");
+    expect(now - rec!.updatedAt.getTime()).toBeLessThan(timeoutMs);
+  });
+
+  test("session stays running when recently updated", () => {
+    const session = storeCreateSession({});
+    storeUpdateSession(session.id, { status: "running" });
+
+    const timeoutMs = 300 * 1000 * 2;
+    const rec = storeGetSession(session.id);
+    expect(rec?.status).toBe("running");
+    expect(Date.now() - rec!.updatedAt.getTime()).toBeLessThan(timeoutMs);
+  });
+});

packages/remote-control-server/src/__tests__/event-bus.test.ts

@@ -0,0 +1,176 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { EventBus, getEventBus, removeEventBus, getAllEventBuses } from "../transport/event-bus";
+
+describe("EventBus", () => {
+  let bus: EventBus;
+
+  beforeEach(() => {
+    bus = new EventBus();
+  });
+
+  describe("publish", () => {
+    test("publishes event with seqNum starting at 1", () => {
+      const event = bus.publish({
+        id: "e1",
+        sessionId: "s1",
+        type: "user",
+        payload: { content: "hello" },
+        direction: "outbound",
+      });
+      expect(event.seqNum).toBe(1);
+      expect(event.createdAt).toBeGreaterThan(0);
+    });
+
+    test("increments seqNum on each publish", () => {
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      bus.publish({ id: "e2", sessionId: "s1", type: "assistant", payload: {}, direction: "inbound" });
+      const event = bus.publish({ id: "e3", sessionId: "s1", type: "result", payload: {}, direction: "inbound" });
+      expect(event.seqNum).toBe(3);
+    });
+
+    test("throws when publishing to a closed bus", () => {
+      bus.close();
+      expect(() =>
+        bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" }),
+      ).toThrow("EventBus is closed");
+    });
+  });
+
+  describe("subscribe", () => {
+    test("receives published events", () => {
+      const received: unknown[] = [];
+      bus.subscribe((event) => received.push(event));
+
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: { content: "hi" }, direction: "outbound" });
+      expect(received).toHaveLength(1);
+      expect((received[0] as any).payload).toEqual({ content: "hi" });
+    });
+
+    test("unsubscribe stops receiving events", () => {
+      const received: unknown[] = [];
+      const unsub = bus.subscribe((event) => received.push(event));
+      unsub();
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      expect(received).toHaveLength(0);
+    });
+
+    test("multiple subscribers all receive events", () => {
+      const r1: unknown[] = [];
+      const r2: unknown[] = [];
+      bus.subscribe((e) => r1.push(e));
+      bus.subscribe((e) => r2.push(e));
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      expect(r1).toHaveLength(1);
+      expect(r2).toHaveLength(1);
+    });
+
+    test("subscriber error does not affect other subscribers", () => {
+      const received: unknown[] = [];
+      bus.subscribe(() => {
+        throw new Error("boom");
+      });
+      bus.subscribe((e) => received.push(e));
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      expect(received).toHaveLength(1);
+    });
+
+    test("subscriberCount", () => {
+      expect(bus.subscriberCount()).toBe(0);
+      const unsub1 = bus.subscribe(() => {});
+      expect(bus.subscriberCount()).toBe(1);
+      const unsub2 = bus.subscribe(() => {});
+      expect(bus.subscriberCount()).toBe(2);
+      unsub1();
+      expect(bus.subscriberCount()).toBe(1);
+    });
+  });
+
+  describe("getEventsSince", () => {
+    test("returns events after given seqNum", () => {
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      bus.publish({ id: "e2", sessionId: "s1", type: "assistant", payload: {}, direction: "inbound" });
+      bus.publish({ id: "e3", sessionId: "s1", type: "result", payload: {}, direction: "inbound" });
+
+      const events = bus.getEventsSince(1);
+      expect(events).toHaveLength(2);
+      expect(events[0].seqNum).toBe(2);
+      expect(events[1].seqNum).toBe(3);
+    });
+
+    test("returns empty for seqNum beyond last", () => {
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      expect(bus.getEventsSince(1)).toHaveLength(0);
+    });
+
+    test("returns all events when seqNum is 0", () => {
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      bus.publish({ id: "e2", sessionId: "s1", type: "assistant", payload: {}, direction: "inbound" });
+      expect(bus.getEventsSince(0)).toHaveLength(2);
+    });
+  });
+
+  describe("getLastSeqNum", () => {
+    test("returns 0 for empty bus", () => {
+      expect(bus.getLastSeqNum()).toBe(0);
+    });
+
+    test("returns last seqNum after publishes", () => {
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      bus.publish({ id: "e2", sessionId: "s1", type: "user", payload: {}, direction: "outbound" });
+      expect(bus.getLastSeqNum()).toBe(2);
+    });
+  });
+
+  describe("close", () => {
+    test("clears subscribers and prevents publishing", () => {
+      bus.subscribe(() => {});
+      bus.close();
+      expect(bus.subscriberCount()).toBe(0);
+      expect(() => bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: {}, direction: "outbound" })).toThrow();
+    });
+  });
+});
+
+describe("EventBus registry", () => {
+  beforeEach(() => {
+    // Clean up global registry
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+  });
+
+  describe("getEventBus", () => {
+    test("creates new bus for unknown session", () => {
+      const bus = getEventBus("s1");
+      expect(bus).toBeInstanceOf(EventBus);
+      expect(getAllEventBuses().has("s1")).toBe(true);
+    });
+
+    test("returns same bus for same session", () => {
+      const bus1 = getEventBus("s1");
+      const bus2 = getEventBus("s1");
+      expect(bus1).toBe(bus2);
+    });
+  });
+
+  describe("removeEventBus", () => {
+    test("removes and closes bus", () => {
+      const bus = getEventBus("s2");
+      removeEventBus("s2");
+      expect(getAllEventBuses().has("s2")).toBe(false);
+      expect(() => bus.publish({ id: "e1", sessionId: "s2", type: "user", payload: {}, direction: "outbound" })).toThrow();
+    });
+
+    test("no-op for non-existent bus", () => {
+      expect(() => removeEventBus("nonexistent")).not.toThrow();
+    });
+  });
+
+  describe("getAllEventBuses", () => {
+    test("returns all registered buses", () => {
+      getEventBus("a");
+      getEventBus("b");
+      expect(getAllEventBuses().size).toBeGreaterThanOrEqual(2);
+    });
+  });
+});

packages/remote-control-server/src/__tests__/middleware.test.ts

@@ -0,0 +1,208 @@
+import { describe, test, expect, beforeEach, afterAll, mock } from "bun:test";
+
+// Mock config before imports
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 8,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { Hono } from "hono";
+import { storeReset, storeCreateUser } from "../store";
+import { apiKeyAuth, sessionIngressAuth, uuidAuth, getUuidFromRequest } from "../auth/middleware";
+import { issueToken } from "../auth/token";
+import { generateWorkerJwt } from "../auth/jwt";
+
+// Helper: create a test app with middleware and a simple handler
+function createTestApp() {
+  const app = new Hono();
+
+  // Test route for apiKeyAuth
+  app.get("/api-key-test", apiKeyAuth, (c) => {
+    return c.json({ username: c.get("username") || null });
+  });
+
+  // Test route for sessionIngressAuth
+  app.get("/ingress/:id", sessionIngressAuth, (c) => {
+    return c.json({ ok: true, jwtPayload: c.get("jwtPayload") || null });
+  });
+
+  // Test route for uuidAuth
+  app.get("/uuid-test", uuidAuth, (c) => {
+    return c.json({ uuid: c.get("uuid") });
+  });
+
+  // Test route for getUuidFromRequest
+  app.get("/uuid-extract", (c) => {
+    return c.json({ uuid: getUuidFromRequest(c) });
+  });
+
+  return app;
+}
+
+describe("Auth Middleware", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    app = createTestApp();
+  });
+
+  describe("apiKeyAuth", () => {
+    test("accepts valid API key with username header", async () => {
+      const res = await app.request("/api-key-test", {
+        headers: {
+          Authorization: "Bearer test-api-key",
+          "X-Username": "alice",
+        },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.username).toBe("alice");
+    });
+
+    test("accepts valid API key with username query param", async () => {
+      const res = await app.request("/api-key-test?username=bob", {
+        headers: { Authorization: "Bearer test-api-key" },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.username).toBe("bob");
+    });
+
+    test("accepts valid session token", async () => {
+      storeCreateUser("charlie");
+      const { token } = issueToken("charlie");
+      const res = await app.request("/api-key-test", {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.username).toBe("charlie");
+    });
+
+    test("rejects invalid token", async () => {
+      const res = await app.request("/api-key-test", {
+        headers: { Authorization: "Bearer wrong-key" },
+      });
+      expect(res.status).toBe(401);
+    });
+
+    test("rejects missing token", async () => {
+      const res = await app.request("/api-key-test");
+      expect(res.status).toBe(401);
+    });
+
+    test("accepts token from query param", async () => {
+      storeCreateUser("dave");
+      const { token } = issueToken("dave");
+      const res = await app.request(`/api-key-test?token=${token}`);
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.username).toBe("dave");
+    });
+  });
+
+  describe("sessionIngressAuth", () => {
+    const originalKeys = process.env.RCS_API_KEYS;
+    beforeEach(() => {
+      process.env.RCS_API_KEYS = "test-api-key";
+    });
+    afterAll(() => {
+      process.env.RCS_API_KEYS = originalKeys;
+    });
+
+    test("accepts valid API key", async () => {
+      const res = await app.request("/ingress/ses_123", {
+        headers: { Authorization: "Bearer test-api-key" },
+      });
+      expect(res.status).toBe(200);
+    });
+
+    test("accepts valid JWT with matching session_id", async () => {
+      const jwt = generateWorkerJwt("ses_123", 3600);
+      const res = await app.request("/ingress/ses_123", {
+        headers: { Authorization: `Bearer ${jwt}` },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.jwtPayload).not.toBeNull();
+      expect(body.jwtPayload.session_id).toBe("ses_123");
+    });
+
+    test("rejects JWT with mismatched session_id", async () => {
+      const jwt = generateWorkerJwt("ses_456", 3600);
+      const res = await app.request("/ingress/ses_123", {
+        headers: { Authorization: `Bearer ${jwt}` },
+      });
+      expect(res.status).toBe(403);
+    });
+
+    test("rejects missing token", async () => {
+      const res = await app.request("/ingress/ses_123");
+      expect(res.status).toBe(401);
+    });
+
+    test("rejects invalid token", async () => {
+      const res = await app.request("/ingress/ses_123", {
+        headers: { Authorization: "Bearer invalid" },
+      });
+      expect(res.status).toBe(401);
+    });
+  });
+
+  describe("uuidAuth", () => {
+    test("accepts UUID from query param", async () => {
+      const res = await app.request("/uuid-test?uuid=test-uuid-1");
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.uuid).toBe("test-uuid-1");
+    });
+
+    test("accepts UUID from header", async () => {
+      const res = await app.request("/uuid-test", {
+        headers: { "X-UUID": "test-uuid-2" },
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.uuid).toBe("test-uuid-2");
+    });
+
+    test("rejects missing UUID", async () => {
+      const res = await app.request("/uuid-test");
+      expect(res.status).toBe(401);
+    });
+  });
+
+  describe("getUuidFromRequest", () => {
+    test("extracts from query param", async () => {
+      const res = await app.request("/uuid-extract?uuid=from-query");
+      const body = await res.json();
+      expect(body.uuid).toBe("from-query");
+    });
+
+    test("extracts from header", async () => {
+      const res = await app.request("/uuid-extract", {
+        headers: { "X-UUID": "from-header" },
+      });
+      const body = await res.json();
+      expect(body.uuid).toBe("from-header");
+    });
+
+    test("returns undefined when no UUID", async () => {
+      const res = await app.request("/uuid-extract");
+      const body = await res.json();
+      expect(body.uuid).toBeUndefined();
+    });
+  });
+});

packages/remote-control-server/src/__tests__/routes.test.ts

@@ -0,0 +1,906 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+// Mock config
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 1,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { Hono } from "hono";
+import { storeReset, storeCreateSession, storeCreateEnvironment, storeBindSession } from "../store";
+import { removeEventBus, getAllEventBuses } from "../transport/event-bus";
+import { issueToken } from "../auth/token";
+
+// Import route modules
+import v1Sessions from "../routes/v1/sessions";
+import v1Environments from "../routes/v1/environments";
+import v1EnvironmentsWork from "../routes/v1/environments.work";
+import v1SessionIngress from "../routes/v1/session-ingress";
+import v2CodeSessions from "../routes/v2/code-sessions";
+import v2Worker from "../routes/v2/worker";
+import v2WorkerEvents from "../routes/v2/worker-events";
+import webAuth from "../routes/web/auth";
+import webSessions from "../routes/web/sessions";
+import webControl from "../routes/web/control";
+import webEnvironments from "../routes/web/environments";
+
+function createApp() {
+  const app = new Hono();
+  app.route("/v1/sessions", v1Sessions);
+  app.route("/v1/environments", v1Environments);
+  app.route("/v1/environments", v1EnvironmentsWork);
+  app.route("/v2/session_ingress", v1SessionIngress);
+  app.route("/v1/code/sessions", v2CodeSessions);
+  app.route("/v1/code/sessions", v2Worker);
+  app.route("/v1/code/sessions", v2WorkerEvents);
+  app.route("/web", webAuth);
+  app.route("/web", webSessions);
+  app.route("/web", webControl);
+  app.route("/web", webEnvironments);
+  return app;
+}
+
+const AUTH_HEADERS = { Authorization: "Bearer test-api-key", "X-Username": "testuser" };
+
+describe("V1 Session Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+    app = createApp();
+  });
+
+  test("POST /v1/sessions — creates a session", async () => {
+    const res = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Test Session" }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.id).toMatch(/^session_/);
+    expect(body.title).toBe("Test Session");
+    expect(body.status).toBe("idle");
+  });
+
+  test("POST /v1/sessions — requires auth", async () => {
+    const res = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("GET /v1/sessions/:id — returns created session", async () => {
+    const createRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const getRes = await app.request(`/v1/sessions/${id}`, {
+      headers: AUTH_HEADERS,
+    });
+    expect(getRes.status).toBe(200);
+    const body = await getRes.json();
+    expect(body.id).toBe(id);
+  });
+
+  test("GET /v1/sessions/:id — 404 for unknown session", async () => {
+    const res = await app.request("/v1/sessions/nope", {
+      headers: AUTH_HEADERS,
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test("PATCH /v1/sessions/:id — updates title", async () => {
+    const createRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const patchRes = await app.request(`/v1/sessions/${id}`, {
+      method: "PATCH",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Updated Title" }),
+    });
+    expect(patchRes.status).toBe(200);
+    const body = await patchRes.json();
+    expect(body.title).toBe("Updated Title");
+  });
+
+  test("POST /v1/sessions/:id/archive — archives session", async () => {
+    const createRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const archiveRes = await app.request(`/v1/sessions/${id}/archive`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(archiveRes.status).toBe(200);
+  });
+
+  test("POST /v1/sessions/:id/events — publishes events", async () => {
+    const createRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const eventsRes = await app.request(`/v1/sessions/${id}/events`, {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ events: [{ type: "user", content: "hello" }] }),
+    });
+    expect(eventsRes.status).toBe(200);
+    const body = await eventsRes.json();
+    expect(body.events).toBe(1);
+  });
+
+  test("POST /v1/sessions with environment_id creates work item", async () => {
+    // First register an environment
+    const envRes = await app.request("/v1/environments/bridge", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ machine_name: "test" }),
+    });
+    const { environment_id } = await envRes.json();
+
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ environment_id }),
+    });
+    expect(sessRes.status).toBe(200);
+    const body = await sessRes.json();
+    expect(body.environment_id).toBe(environment_id);
+  });
+
+  test("POST /v1/sessions with invalid environment_id — session created, work item fails silently", async () => {
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ environment_id: "env_nonexistent" }),
+    });
+    expect(sessRes.status).toBe(200);
+    const body = await sessRes.json();
+    expect(body.id).toMatch(/^session_/);
+  });
+
+  test("POST /v1/sessions with events — publishes initial events", async () => {
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ events: [{ type: "init", data: "starting" }] }),
+    });
+    expect(sessRes.status).toBe(200);
+  });
+});
+
+describe("V1 Environment Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    app = createApp();
+  });
+
+  test("POST /v1/environments/bridge — registers environment", async () => {
+    const res = await app.request("/v1/environments/bridge", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ machine_name: "mac1", directory: "/home" }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.environment_id).toMatch(/^env_/);
+    expect(body.status).toBe("active");
+  });
+
+  test("DELETE /v1/environments/bridge/:id — deregisters environment", async () => {
+    const envRes = await app.request("/v1/environments/bridge", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { environment_id } = await envRes.json();
+
+    const delRes = await app.request(`/v1/environments/bridge/${environment_id}`, {
+      method: "DELETE",
+      headers: AUTH_HEADERS,
+    });
+    expect(delRes.status).toBe(200);
+  });
+
+  test("POST /v1/environments/:id/bridge/reconnect — reconnects environment", async () => {
+    const envRes = await app.request("/v1/environments/bridge", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { environment_id } = await envRes.json();
+
+    const reconnectRes = await app.request(`/v1/environments/${environment_id}/bridge/reconnect`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(reconnectRes.status).toBe(200);
+  });
+});
+
+describe("V1 Work Routes", () => {
+  let app: Hono;
+  let envId: string;
+
+  beforeEach(async () => {
+    storeReset();
+    app = createApp();
+
+    const envRes = await app.request("/v1/environments/bridge", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    envId = (await envRes.json()).environment_id;
+  });
+
+  test("GET /v1/environments/:id/work/poll — returns 204 when no work", async () => {
+    const res = await app.request(`/v1/environments/${envId}/work/poll`, {
+      headers: AUTH_HEADERS,
+    });
+    expect(res.status).toBe(204);
+  });
+
+  test("work lifecycle: create → poll → ack → stop", async () => {
+    // Create session with environment (creates work item)
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ environment_id: envId }),
+    });
+    const sessionId = (await sessRes.json()).id;
+
+    // Poll for work
+    const pollRes = await app.request(`/v1/environments/${envId}/work/poll`, {
+      headers: AUTH_HEADERS,
+    });
+    expect(pollRes.status).toBe(200);
+    const work = await pollRes.json();
+    expect(work.id).toMatch(/^work_/);
+    expect(work.data.id).toBe(sessionId);
+
+    // Ack work
+    const ackRes = await app.request(`/v1/environments/${envId}/work/${work.id}/ack`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(ackRes.status).toBe(200);
+
+    // Stop work
+    const stopRes = await app.request(`/v1/environments/${envId}/work/${work.id}/stop`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(stopRes.status).toBe(200);
+  });
+
+  test("POST work heartbeat", async () => {
+    // Create session + work
+    await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ environment_id: envId }),
+    });
+    const pollRes = await app.request(`/v1/environments/${envId}/work/poll`, {
+      headers: AUTH_HEADERS,
+    });
+    const work = await pollRes.json();
+
+    const hbRes = await app.request(`/v1/environments/${envId}/work/${work.id}/heartbeat`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(hbRes.status).toBe(200);
+    const body = await hbRes.json();
+    expect(body.lease_extended).toBe(true);
+  });
+});
+
+describe("V2 Code Session Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    process.env.RCS_API_KEYS = "test-api-key";
+    app = createApp();
+  });
+
+  test("POST /v1/code/sessions — creates code session", async () => {
+    const res = await app.request("/v1/code/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Code Session" }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.session.id).toMatch(/^cse_/);
+    expect(body.session.title).toBe("Code Session");
+  });
+
+  test("POST /v1/code/sessions/:id/bridge — returns bridge info with JWT", async () => {
+    // Create code session
+    const createRes = await app.request("/v1/code/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = (await createRes.json()).session;
+
+    const bridgeRes = await app.request(`/v1/code/sessions/${id}/bridge`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(bridgeRes.status).toBe(200);
+    const body = await bridgeRes.json();
+    expect(body.api_base_url).toBe("http://localhost:3000");
+    expect(body.worker_epoch).toBe(1);
+    expect(body.worker_jwt).toBeTruthy();
+    expect(body.expires_in).toBe(3600);
+  });
+
+  test("POST /v1/code/sessions/:id/bridge — 404 for unknown session", async () => {
+    const res = await app.request("/v1/code/sessions/nope/bridge", {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("V2 Worker Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    process.env.RCS_API_KEYS = "test-api-key";
+    app = createApp();
+  });
+
+  test("POST /v1/code/sessions/:id/worker/register — increments epoch", async () => {
+    // Create session
+    const createRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const regRes = await app.request(`/v1/code/sessions/${id}/worker/register`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(regRes.status).toBe(200);
+    const body = await regRes.json();
+    expect(body.worker_epoch).toBe(1);
+  });
+
+  test("POST /v1/code/sessions/:id/worker/register — 404 for unknown", async () => {
+    const res = await app.request("/v1/code/sessions/nope/worker/register", {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("Web Auth Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    app = createApp();
+  });
+
+  test("POST /web/bind — binds session to UUID", async () => {
+    // Create session first
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await sessRes.json();
+
+    const bindRes = await app.request("/web/bind?uuid=test-uuid", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sessionId: id }),
+    });
+    expect(bindRes.status).toBe(200);
+    const body = await bindRes.json();
+    expect(body.ok).toBe(true);
+  });
+
+  test("POST /web/bind — 404 for unknown session", async () => {
+    const res = await app.request("/web/bind?uuid=test-uuid", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sessionId: "nope" }),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test("POST /web/bind — 400 when missing params", async () => {
+    const res = await app.request("/web/bind", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("Web Session Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+    app = createApp();
+  });
+
+  test("POST /web/sessions — creates and auto-binds session", async () => {
+    const res = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Web Session" }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.id).toMatch(/^session_/);
+    expect(body.source).toBe("web");
+  });
+
+  test("GET /web/sessions — returns sessions owned by UUID", async () => {
+    // Create and bind
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const listRes = await app.request("/web/sessions?uuid=user-1");
+    expect(listRes.status).toBe(200);
+    const sessions = await listRes.json();
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].id).toBe(id);
+  });
+
+  test("GET /web/sessions — requires UUID", async () => {
+    const res = await app.request("/web/sessions");
+    expect(res.status).toBe(401);
+  });
+
+  test("GET /web/sessions/all — lists only sessions owned by requesting UUID", async () => {
+    // Create 2 sessions via different users
+    await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    await app.request("/web/sessions?uuid=user-2", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+
+    const allRes = await app.request("/web/sessions/all?uuid=user-1");
+    expect(allRes.status).toBe(200);
+    const sessions = await allRes.json();
+    expect(sessions).toHaveLength(1); // only user-1's session, not user-2's
+  });
+
+  test("GET /web/sessions/:id — returns owned session", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const getRes = await app.request(`/web/sessions/${id}?uuid=user-1`);
+    expect(getRes.status).toBe(200);
+  });
+
+  test("GET /web/sessions/:id — 403 for non-owner", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const getRes = await app.request(`/web/sessions/${id}?uuid=user-2`);
+    expect(getRes.status).toBe(403);
+  });
+
+  test("GET /web/sessions/:id/history — returns events", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const histRes = await app.request(`/web/sessions/${id}/history?uuid=user-1`);
+    expect(histRes.status).toBe(200);
+    const body = await histRes.json();
+    expect(body.events).toEqual([]);
+  });
+
+  test("GET /web/sessions/:id/history — 403 for non-owner", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const histRes = await app.request(`/web/sessions/${id}/history?uuid=user-2`);
+    expect(histRes.status).toBe(403);
+  });
+
+  test("GET /web/sessions/:id — 404 after session deleted", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    // Archive/delete the session via v1
+    await app.request(`/v1/sessions/${id}/archive`, {
+      method: "POST",
+      headers: AUTH_HEADERS,
+    });
+
+    // Session still exists (archived), so we can still get it
+    const getRes = await app.request(`/web/sessions/${id}?uuid=user-1`);
+    // After archive, session status is "archived" but still exists
+    expect(getRes.status).toBe(200);
+  });
+
+  test("GET /web/sessions/:id/history — 404 for non-existent session", async () => {
+    // Bind to a non-existent session won't work, but if ownership was set
+    // and session deleted, we need to test the 404 path
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    // Delete the session from store directly
+    const { storeDeleteSession } = await import("../store");
+    storeDeleteSession(id);
+
+    const histRes = await app.request(`/web/sessions/${id}/history?uuid=user-1`);
+    expect(histRes.status).toBe(404);
+  });
+
+  test("POST /web/sessions with invalid environment_id — handles work item error", async () => {
+    const res = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ environment_id: "env_nonexistent" }),
+    });
+    // Session is still created even if work item fails
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.id).toMatch(/^session_/);
+  });
+
+  test("GET /web/sessions/:id/events — returns SSE stream", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const eventsRes = await app.request(`/web/sessions/${id}/events?uuid=user-1`);
+    expect(eventsRes.status).toBe(200);
+    expect(eventsRes.headers.get("Content-Type")).toBe("text/event-stream");
+
+    // Read initial keepalive and cancel
+    const reader = eventsRes.body?.getReader();
+    if (reader) {
+      const { value } = await reader.read();
+      const text = new TextDecoder().decode(value!);
+      expect(text).toContain(": keepalive");
+      reader.cancel();
+    }
+  });
+
+  test("GET /web/sessions/:id/events — 403 for non-owner", async () => {
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await createRes.json();
+
+    const eventsRes = await app.request(`/web/sessions/${id}/events?uuid=user-2`);
+    expect(eventsRes.status).toBe(403);
+  });
+});
+
+describe("Web Control Routes", () => {
+  let app: Hono;
+  let sessionId: string;
+
+  beforeEach(async () => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+    app = createApp();
+
+    // Create and bind session
+    const createRes = await app.request("/web/sessions?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    sessionId = (await createRes.json()).id;
+  });
+
+  test("POST /web/sessions/:id/events — sends user message", async () => {
+    const res = await app.request(`/web/sessions/${sessionId}/events?uuid=user-1`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "user", content: "hello" }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+    expect(body.event).toBeTruthy();
+  });
+
+  test("POST /web/sessions/:id/events — 403 for non-owner", async () => {
+    const res = await app.request(`/web/sessions/${sessionId}/events?uuid=user-2`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "user", content: "hello" }),
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("POST /web/sessions/:id/control — sends control request", async () => {
+    const res = await app.request(`/web/sessions/${sessionId}/control?uuid=user-1`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "permission_response", approved: true, request_id: "r1" }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("POST /web/sessions/:id/interrupt — interrupts session", async () => {
+    const res = await app.request(`/web/sessions/${sessionId}/interrupt?uuid=user-1`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("POST /web/sessions/:id/interrupt — 403 for non-owner", async () => {
+    const res = await app.request(`/web/sessions/${sessionId}/interrupt?uuid=user-2`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("POST /web/sessions/:id/control — 403 for non-owner", async () => {
+    const res = await app.request(`/web/sessions/${sessionId}/control?uuid=user-2`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "permission_response", approved: true }),
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("POST /web/sessions/:id/events — 403 for non-existent session with no ownership", async () => {
+    const res = await app.request("/web/sessions/nonexistent/events?uuid=user-1", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "user", content: "hello" }),
+    });
+    expect(res.status).toBe(403);
+  });
+});
+
+describe("Web Environment Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    app = createApp();
+  });
+
+  test("GET /web/environments — lists active environments", async () => {
+    // Register an env via v1
+    await app.request("/v1/environments/bridge", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ machine_name: "mac1" }),
+    });
+
+    const res = await app.request("/web/environments?uuid=user-1");
+    expect(res.status).toBe(200);
+    const envs = await res.json();
+    expect(envs).toHaveLength(1);
+    expect(envs[0].machine_name).toBe("mac1");
+  });
+
+  test("GET /web/environments — requires UUID", async () => {
+    const res = await app.request("/web/environments");
+    expect(res.status).toBe(401);
+  });
+});
+
+describe("V1 Session Ingress Routes (HTTP)", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+    process.env.RCS_API_KEYS = "test-api-key";
+    app = createApp();
+  });
+
+  test("POST /v2/session_ingress/session/:sessionId/events — ingests events with API key", async () => {
+    // Create session first
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await sessRes.json();
+
+    const res = await app.request(`/v2/session_ingress/session/${id}/events`, {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ events: [{ type: "assistant", content: "response" }] }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+  });
+
+  test("POST /v2/session_ingress/session/:sessionId/events — rejects without auth", async () => {
+    const res = await app.request("/v2/session_ingress/session/nope/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ events: [] }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("POST /v2/session_ingress/session/:sessionId/events — 404 for unknown session", async () => {
+    const res = await app.request("/v2/session_ingress/session/nope/events", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ events: [{ type: "user", content: "hi" }] }),
+    });
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("V2 Worker Events Routes", () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+    process.env.RCS_API_KEYS = "test-api-key";
+    app = createApp();
+  });
+
+  test("POST /v1/code/sessions/:id/worker/events — publishes worker events", async () => {
+    // Create session
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await sessRes.json();
+
+    const res = await app.request(`/v1/code/sessions/${id}/worker/events`, {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify([{ type: "assistant", content: "response" }]),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+    expect(body.count).toBe(1);
+  });
+
+  test("PUT /v1/code/sessions/:id/worker/state — updates session status", async () => {
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await sessRes.json();
+
+    const res = await app.request(`/v1/code/sessions/${id}/worker/state`, {
+      method: "PUT",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ status: "running" }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("PUT /v1/code/sessions/:id/worker/external_metadata — no-op", async () => {
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await sessRes.json();
+
+    const res = await app.request(`/v1/code/sessions/${id}/worker/external_metadata`, {
+      method: "PUT",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ meta: "data" }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("POST /v1/code/sessions/:id/worker/events/:eventId/delivery — no-op", async () => {
+    const sessRes = await app.request("/v1/sessions", {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const { id } = await sessRes.json();
+
+    const res = await app.request(`/v1/code/sessions/${id}/worker/events/evt123/delivery`, {
+      method: "POST",
+      headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
+      body: JSON.stringify({ status: "received" }),
+    });
+    expect(res.status).toBe(200);
+  });
+});

packages/remote-control-server/src/__tests__/services.test.ts

@@ -0,0 +1,386 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+// Mock config before importing modules
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 8,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { storeReset, storeCreateEnvironment } from "../store";
+import {
+  createSession,
+  createCodeSession,
+  getSession,
+  updateSessionTitle,
+  updateSessionStatus,
+  archiveSession,
+  incrementEpoch,
+  listSessions,
+  listSessionSummaries,
+  listSessionSummariesByUsername,
+  listSessionsByEnvironment,
+} from "../services/session";
+import {
+  registerEnvironment,
+  deregisterEnvironment,
+  getEnvironment,
+  updatePollTime,
+  listActiveEnvironments,
+  listActiveEnvironmentsResponse,
+  listActiveEnvironmentsByUsername,
+  reconnectEnvironment,
+} from "../services/environment";
+import { normalizePayload, publishSessionEvent } from "../services/transport";
+import { getEventBus, removeEventBus, getAllEventBuses } from "../transport/event-bus";
+
+// ---------- Session Service ----------
+
+describe("Session Service", () => {
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+  });
+
+  describe("createSession", () => {
+    test("creates a session with defaults", () => {
+      const resp = createSession({});
+      expect(resp.id).toMatch(/^session_/);
+      expect(resp.status).toBe("idle");
+      expect(resp.source).toBe("remote-control");
+      expect(resp.environment_id).toBeNull();
+      expect(resp.worker_epoch).toBe(0);
+      expect(resp.created_at).toBeGreaterThan(0);
+    });
+
+    test("creates a session with all options", () => {
+      const env = storeCreateEnvironment({ secret: "s" });
+      const resp = createSession({
+        environment_id: env.id,
+        title: "My Session",
+        source: "cli",
+        permission_mode: "auto",
+      });
+      expect(resp.environment_id).toBe(env.id);
+      expect(resp.title).toBe("My Session");
+      expect(resp.source).toBe("cli");
+      expect(resp.permission_mode).toBe("auto");
+    });
+
+    test("creates session with username", () => {
+      const resp = createSession({ username: "alice" });
+      expect(resp.username).toBe("alice");
+    });
+  });
+
+  describe("createCodeSession", () => {
+    test("creates a code session with cse_ prefix", () => {
+      const resp = createCodeSession({});
+      expect(resp.id).toMatch(/^cse_/);
+    });
+  });
+
+  describe("getSession", () => {
+    test("returns null for non-existent session", () => {
+      expect(getSession("nope")).toBeNull();
+    });
+
+    test("returns created session", () => {
+      const created = createSession({});
+      const fetched = getSession(created.id);
+      expect(fetched).not.toBeNull();
+      expect(fetched!.id).toBe(created.id);
+    });
+  });
+
+  describe("updateSessionTitle", () => {
+    test("updates title", () => {
+      const s = createSession({});
+      updateSessionTitle(s.id, "New Title");
+      expect(getSession(s.id)?.title).toBe("New Title");
+    });
+  });
+
+  describe("updateSessionStatus", () => {
+    test("updates status", () => {
+      const s = createSession({});
+      updateSessionStatus(s.id, "active");
+      expect(getSession(s.id)?.status).toBe("active");
+    });
+  });
+
+  describe("archiveSession", () => {
+    test("sets status to archived and removes event bus", () => {
+      const s = createSession({});
+      // Create event bus for this session
+      getEventBus(s.id);
+      archiveSession(s.id);
+      expect(getSession(s.id)?.status).toBe("archived");
+      expect(getAllEventBuses().has(s.id)).toBe(false);
+    });
+  });
+
+  describe("incrementEpoch", () => {
+    test("increments epoch by 1", () => {
+      const s = createSession({});
+      expect(incrementEpoch(s.id)).toBe(1);
+      expect(incrementEpoch(s.id)).toBe(2);
+      expect(getSession(s.id)?.worker_epoch).toBe(2);
+    });
+
+    test("throws for non-existent session", () => {
+      expect(() => incrementEpoch("nope")).toThrow("Session not found");
+    });
+  });
+
+  describe("listSessions", () => {
+    test("returns all sessions", () => {
+      createSession({});
+      createSession({});
+      expect(listSessions()).toHaveLength(2);
+    });
+  });
+
+  describe("listSessionSummaries", () => {
+    test("returns summaries with correct fields", () => {
+      createSession({ title: "Test" });
+      const summaries = listSessionSummaries();
+      expect(summaries).toHaveLength(1);
+      expect(summaries[0].title).toBe("Test");
+      expect(summaries[0].updated_at).toBeGreaterThan(0);
+      // Summary should not have environment_id
+      expect("environment_id" in summaries[0]).toBe(false);
+    });
+  });
+
+  describe("listSessionSummariesByUsername", () => {
+    test("filters by username", () => {
+      createSession({ username: "alice" });
+      createSession({ username: "bob" });
+      expect(listSessionSummariesByUsername("alice")).toHaveLength(1);
+    });
+  });
+
+  describe("listSessionsByEnvironment", () => {
+    test("filters by environment", () => {
+      const env = storeCreateEnvironment({ secret: "s" });
+      createSession({ environment_id: env.id });
+      createSession({});
+      expect(listSessionsByEnvironment(env.id)).toHaveLength(1);
+    });
+  });
+});
+
+// ---------- Environment Service ----------
+
+describe("Environment Service", () => {
+  beforeEach(() => {
+    storeReset();
+  });
+
+  describe("registerEnvironment", () => {
+    test("registers environment with defaults", () => {
+      const result = registerEnvironment({});
+      expect(result.environment_id).toMatch(/^env_/);
+      expect(result.environment_secret).toBe("test-api-key");
+      expect(result.status).toBe("active");
+    });
+
+    test("registers with options", () => {
+      const result = registerEnvironment({
+        machine_name: "mac1",
+        directory: "/home/user",
+        branch: "main",
+        git_repo_url: "https://github.com/test/repo",
+        max_sessions: 5,
+        worker_type: "custom",
+      });
+      const env = getEnvironment(result.environment_id);
+      expect(env?.machineName).toBe("mac1");
+      expect(env?.directory).toBe("/home/user");
+      expect(env?.maxSessions).toBe(5);
+    });
+
+    test("registers with username", () => {
+      const result = registerEnvironment({ username: "alice" });
+      const env = getEnvironment(result.environment_id);
+      expect(env?.username).toBe("alice");
+    });
+  });
+
+  describe("deregisterEnvironment", () => {
+    test("sets status to deregistered", () => {
+      const result = registerEnvironment({});
+      deregisterEnvironment(result.environment_id);
+      const env = getEnvironment(result.environment_id);
+      expect(env?.status).toBe("deregistered");
+    });
+  });
+
+  describe("updatePollTime", () => {
+    test("updates lastPollAt", () => {
+      const result = registerEnvironment({});
+      const before = getEnvironment(result.environment_id)?.lastPollAt;
+      // Small delay to ensure time difference
+      updatePollTime(result.environment_id);
+      const after = getEnvironment(result.environment_id)?.lastPollAt;
+      expect(after!.getTime()).toBeGreaterThanOrEqual(before!.getTime());
+    });
+  });
+
+  describe("listActiveEnvironments", () => {
+    test("returns active environments", () => {
+      registerEnvironment({});
+      registerEnvironment({});
+      expect(listActiveEnvironments()).toHaveLength(2);
+    });
+  });
+
+  describe("listActiveEnvironmentsResponse", () => {
+    test("returns response format", () => {
+      registerEnvironment({ machine_name: "mac1" });
+      const envs = listActiveEnvironmentsResponse();
+      expect(envs).toHaveLength(1);
+      expect(envs[0].machine_name).toBe("mac1");
+      expect(envs[0].last_poll_at).toBeGreaterThan(0);
+    });
+  });
+
+  describe("listActiveEnvironmentsByUsername", () => {
+    test("filters by username", () => {
+      registerEnvironment({ username: "alice" });
+      registerEnvironment({ username: "bob" });
+      expect(listActiveEnvironmentsByUsername("alice")).toHaveLength(1);
+    });
+  });
+
+  describe("reconnectEnvironment", () => {
+    test("sets status back to active", () => {
+      const result = registerEnvironment({});
+      deregisterEnvironment(result.environment_id);
+      expect(getEnvironment(result.environment_id)?.status).toBe("deregistered");
+      reconnectEnvironment(result.environment_id);
+      expect(getEnvironment(result.environment_id)?.status).toBe("active");
+    });
+  });
+});
+
+// ---------- Transport Service ----------
+
+describe("Transport Service", () => {
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+  });
+
+  describe("normalizePayload", () => {
+    test("handles string payload", () => {
+      const result = normalizePayload("user", "hello world");
+      expect(result.content).toBe("hello world");
+      expect(result.raw).toBe("hello world");
+    });
+
+    test("handles null payload", () => {
+      const result = normalizePayload("user", null);
+      expect(result.content).toBe("");
+      expect(result.raw).toBeNull();
+    });
+
+    test("handles object with direct content", () => {
+      const result = normalizePayload("user", { content: "direct text" });
+      expect(result.content).toBe("direct text");
+    });
+
+    test("handles object with message.content string", () => {
+      const result = normalizePayload("assistant", { message: { role: "assistant", content: "reply" } });
+      expect(result.content).toBe("reply");
+    });
+
+    test("handles object with message.content array", () => {
+      const result = normalizePayload("assistant", {
+        message: {
+          content: [
+            { type: "text", text: "hello " },
+            { type: "text", text: "world" },
+          ],
+        },
+      });
+      expect(result.content).toBe("hello world");
+    });
+
+    test("preserves tool fields", () => {
+      const result = normalizePayload("tool_use", { tool_name: "Bash", tool_input: { cmd: "ls" } });
+      expect(result.tool_name).toBe("Bash");
+      expect(result.tool_input).toEqual({ cmd: "ls" });
+    });
+
+    test("preserves permission fields", () => {
+      const result = normalizePayload("permission", {
+        request_id: "req_1",
+        approved: true,
+        updated_input: { cmd: "ls -la" },
+      });
+      expect(result.request_id).toBe("req_1");
+      expect(result.approved).toBe(true);
+      expect(result.updated_input).toEqual({ cmd: "ls -la" });
+    });
+
+    test("preserves message field", () => {
+      const msg = { role: "user", content: "hi" };
+      const result = normalizePayload("user", { message: msg });
+      expect(result.message).toEqual(msg);
+    });
+
+    test("uses name as tool_name fallback", () => {
+      const result = normalizePayload("tool", { name: "Read" });
+      expect(result.tool_name).toBe("Read");
+    });
+
+    test("uses input as tool_input fallback", () => {
+      const result = normalizePayload("tool", { input: { path: "/tmp" } });
+      expect(result.tool_input).toEqual({ path: "/tmp" });
+    });
+
+    test("handles empty content array", () => {
+      const result = normalizePayload("assistant", {
+        message: { content: [] },
+      });
+      expect(result.content).toBe("");
+    });
+
+    test("handles undefined payload", () => {
+      const result = normalizePayload("user", undefined);
+      expect(result.content).toBe("");
+    });
+  });
+
+  describe("publishSessionEvent", () => {
+    test("publishes event to session bus", () => {
+      const event = publishSessionEvent("s1", "user", { content: "hello" }, "outbound");
+      expect(event.type).toBe("user");
+      expect(event.direction).toBe("outbound");
+      expect(event.sessionId).toBe("s1");
+      expect(event.seqNum).toBe(1);
+    });
+
+    test("normalizes payload before publishing", () => {
+      const event = publishSessionEvent("s1", "assistant", { message: { content: "reply" } }, "inbound");
+      const payload = event.payload as Record<string, unknown>;
+      expect(payload.content).toBe("reply");
+    });
+  });
+});

packages/remote-control-server/src/__tests__/sse-writer.test.ts

@@ -0,0 +1,179 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+// Mock config
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 8,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { Hono } from "hono";
+import { storeReset } from "../store";
+import { removeEventBus, getAllEventBuses, getEventBus } from "../transport/event-bus";
+import { createSSEWriter, createSSEStream } from "../transport/sse-writer";
+
+/** Read up to N bytes from a Response stream, then cancel */
+async function readPartialStream(res: Response, maxBytes = 4096): Promise<string> {
+  const reader = res.body?.getReader();
+  if (!reader) return "";
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+  try {
+    while (totalBytes < maxBytes) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      totalBytes += value.length;
+      // Cancel after we have some data (first keepalive + any initial events)
+      if (totalBytes > 0) break;
+    }
+  } finally {
+    reader.cancel();
+  }
+  const combined = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return new TextDecoder().decode(combined);
+}
+
+describe("SSE Writer", () => {
+  describe("createSSEWriter", () => {
+    test("creates SSEWriter with send and close methods", () => {
+      const app = new Hono();
+      let capturedWriter: ReturnType<typeof createSSEWriter> | null = null;
+
+      app.get("/test", (c) => {
+        capturedWriter = createSSEWriter(c);
+        return c.text("ok");
+      });
+
+      app.request("/test");
+      expect(capturedWriter).not.toBeNull();
+      expect(typeof capturedWriter!.send).toBe("function");
+      expect(typeof capturedWriter!.close).toBe("function");
+    });
+  });
+
+  describe("createSSEStream", () => {
+    beforeEach(() => {
+      storeReset();
+      for (const [key] of getAllEventBuses()) {
+        removeEventBus(key);
+      }
+    });
+
+    test("returns Response with correct SSE headers", async () => {
+      const app = new Hono();
+
+      app.get("/stream/:sessionId", (c) => {
+        const sessionId = c.req.param("sessionId");
+        return createSSEStream(c, sessionId, 0);
+      });
+
+      const res = await app.request("/stream/s1");
+      expect(res.status).toBe(200);
+      expect(res.headers.get("Content-Type")).toBe("text/event-stream");
+      expect(res.headers.get("Cache-Control")).toBe("no-cache");
+      expect(res.headers.get("Connection")).toBe("keep-alive");
+      expect(res.headers.get("X-Accel-Buffering")).toBe("no");
+
+      // Cancel the stream
+      res.body?.cancel();
+    });
+
+    test("sends initial keepalive", async () => {
+      const app = new Hono();
+
+      app.get("/stream/:sessionId", (c) => {
+        const sessionId = c.req.param("sessionId");
+        return createSSEStream(c, sessionId, 0);
+      });
+
+      const res = await app.request("/stream/s2");
+      const text = await readPartialStream(res);
+      expect(text).toContain(": keepalive");
+    });
+
+    test("sends historical events when fromSeqNum > 0", async () => {
+      // Pre-populate event bus with events
+      const bus = getEventBus("s3");
+      bus.publish({ id: "e1", sessionId: "s3", type: "user", payload: { content: "hello" }, direction: "outbound" });
+      bus.publish({ id: "e2", sessionId: "s3", type: "assistant", payload: { content: "hi" }, direction: "inbound" });
+
+      const app = new Hono();
+
+      app.get("/stream/:sessionId", (c) => {
+        const sessionId = c.req.param("sessionId");
+        const fromSeq = parseInt(c.req.query("fromSeq") || "0");
+        return createSSEStream(c, sessionId, fromSeq);
+      });
+
+      const res = await app.request("/stream/s3?fromSeq=1");
+      const text = await readPartialStream(res);
+      // Should replay events since seq 1 (i.e., event 2)
+      expect(text).toContain('"seqNum":2');
+      expect(text).toContain("assistant");
+    });
+
+    test("no historical events when fromSeqNum is 0", async () => {
+      const bus = getEventBus("s5");
+      bus.publish({ id: "e1", sessionId: "s5", type: "user", payload: {}, direction: "outbound" });
+
+      const app = new Hono();
+
+      app.get("/stream/:sessionId", (c) => {
+        const sessionId = c.req.param("sessionId");
+        return createSSEStream(c, sessionId, 0);
+      });
+
+      const res = await app.request("/stream/s5");
+      const text = await readPartialStream(res);
+      // With fromSeqNum=0, no historical replay, just keepalive
+      expect(text).toContain(": keepalive");
+      // Should NOT contain event data (only keepalive)
+      expect(text).not.toContain("event: message");
+    });
+
+    test("subscribes to new events and delivers them", async () => {
+      const app = new Hono();
+
+      app.get("/stream/:sessionId", (c) => {
+        const sessionId = c.req.param("sessionId");
+        return createSSEStream(c, sessionId, 0);
+      });
+
+      const res = await app.request("/stream/s6");
+
+      // Read initial keepalive first
+      const reader = res.body!.getReader();
+      const { value: firstChunk } = await reader.read();
+      const initialText = new TextDecoder().decode(firstChunk!);
+      expect(initialText).toContain(": keepalive");
+
+      // Now publish an event
+      const bus = getEventBus("s6");
+      bus.publish({ id: "e1", sessionId: "s6", type: "user", payload: { content: "real-time" }, direction: "outbound" });
+
+      // Read the event
+      const { value: secondChunk } = await reader.read();
+      const eventText = new TextDecoder().decode(secondChunk!);
+      expect(eventText).toContain("event: message");
+      expect(eventText).toContain("real-time");
+
+      reader.cancel();
+    });
+  });
+});

packages/remote-control-server/src/__tests__/store.test.ts

@@ -0,0 +1,396 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import {
+  storeReset,
+  storeCreateUser,
+  storeGetUser,
+  storeCreateToken,
+  storeGetUserByToken,
+  storeDeleteToken,
+  storeCreateEnvironment,
+  storeGetEnvironment,
+  storeUpdateEnvironment,
+  storeListActiveEnvironments,
+  storeListActiveEnvironmentsByUsername,
+  storeCreateSession,
+  storeGetSession,
+  storeUpdateSession,
+  storeListSessions,
+  storeListSessionsByUsername,
+  storeListSessionsByEnvironment,
+  storeDeleteSession,
+  storeBindSession,
+  storeIsSessionOwner,
+  storeListSessionsByOwnerUuid,
+  storeCreateWorkItem,
+  storeGetWorkItem,
+  storeGetPendingWorkItem,
+  storeUpdateWorkItem,
+} from "../store";
+
+describe("store", () => {
+  beforeEach(() => {
+    storeReset();
+  });
+
+  // ---------- User ----------
+
+  describe("storeCreateUser", () => {
+    test("creates a new user", () => {
+      const user = storeCreateUser("alice");
+      expect(user.username).toBe("alice");
+      expect(user.createdAt).toBeInstanceOf(Date);
+    });
+
+    test("returns existing user on duplicate create", () => {
+      const first = storeCreateUser("bob");
+      const second = storeCreateUser("bob");
+      expect(first).toBe(second);
+    });
+  });
+
+  describe("storeGetUser", () => {
+    test("returns undefined for non-existent user", () => {
+      expect(storeGetUser("nobody")).toBeUndefined();
+    });
+
+    test("returns created user", () => {
+      storeCreateUser("charlie");
+      const user = storeGetUser("charlie");
+      expect(user?.username).toBe("charlie");
+    });
+  });
+
+  // ---------- Token ----------
+
+  describe("storeCreateToken / storeGetUserByToken", () => {
+    test("creates and resolves token", () => {
+      storeCreateUser("dave");
+      storeCreateToken("dave", "tk_123");
+      const entry = storeGetUserByToken("tk_123");
+      expect(entry?.username).toBe("dave");
+      expect(entry?.createdAt).toBeInstanceOf(Date);
+    });
+
+    test("returns undefined for unknown token", () => {
+      expect(storeGetUserByToken("nonexistent")).toBeUndefined();
+    });
+  });
+
+  describe("storeDeleteToken", () => {
+    test("deletes an existing token", () => {
+      storeCreateUser("eve");
+      storeCreateToken("eve", "tk_del");
+      expect(storeDeleteToken("tk_del")).toBe(true);
+      expect(storeGetUserByToken("tk_del")).toBeUndefined();
+    });
+
+    test("returns false for non-existent token", () => {
+      expect(storeDeleteToken("nope")).toBe(false);
+    });
+  });
+
+  // ---------- Environment ----------
+
+  describe("storeCreateEnvironment", () => {
+    test("creates environment with defaults", () => {
+      const env = storeCreateEnvironment({ secret: "s1" });
+      expect(env.id).toMatch(/^env_/);
+      expect(env.secret).toBe("s1");
+      expect(env.status).toBe("active");
+      expect(env.machineName).toBeNull();
+      expect(env.maxSessions).toBe(1);
+      expect(env.workerType).toBe("claude_code");
+      expect(env.lastPollAt).toBeInstanceOf(Date);
+    });
+
+    test("creates environment with all options", () => {
+      const env = storeCreateEnvironment({
+        secret: "s2",
+        machineName: "mac1",
+        directory: "/home/user",
+        branch: "main",
+        gitRepoUrl: "https://github.com/test/repo",
+        maxSessions: 5,
+        workerType: "custom",
+        bridgeId: "bridge1",
+        username: "alice",
+      });
+      expect(env.machineName).toBe("mac1");
+      expect(env.directory).toBe("/home/user");
+      expect(env.branch).toBe("main");
+      expect(env.gitRepoUrl).toBe("https://github.com/test/repo");
+      expect(env.maxSessions).toBe(5);
+      expect(env.workerType).toBe("custom");
+      expect(env.bridgeId).toBe("bridge1");
+      expect(env.username).toBe("alice");
+    });
+  });
+
+  describe("storeGetEnvironment", () => {
+    test("returns undefined for non-existent env", () => {
+      expect(storeGetEnvironment("env_no")).toBeUndefined();
+    });
+
+    test("returns created environment", () => {
+      const env = storeCreateEnvironment({ secret: "s" });
+      expect(storeGetEnvironment(env.id)).toBe(env);
+    });
+  });
+
+  describe("storeUpdateEnvironment", () => {
+    test("updates existing environment", () => {
+      const env = storeCreateEnvironment({ secret: "s" });
+      const result = storeUpdateEnvironment(env.id, { status: "disconnected" });
+      expect(result).toBe(true);
+      const updated = storeGetEnvironment(env.id);
+      expect(updated?.status).toBe("disconnected");
+      expect(updated?.updatedAt.getTime()).toBeGreaterThanOrEqual(env.updatedAt.getTime());
+    });
+
+    test("returns false for non-existent environment", () => {
+      expect(storeUpdateEnvironment("env_no", { status: "active" })).toBe(false);
+    });
+  });
+
+  describe("storeListActiveEnvironments", () => {
+    test("returns only active environments", () => {
+      const env1 = storeCreateEnvironment({ secret: "s1" });
+      const env2 = storeCreateEnvironment({ secret: "s2" });
+      storeUpdateEnvironment(env1.id, { status: "deregistered" });
+      const active = storeListActiveEnvironments();
+      expect(active).toHaveLength(1);
+      expect(active[0].id).toBe(env2.id);
+    });
+  });
+
+  describe("storeListActiveEnvironmentsByUsername", () => {
+    test("filters by username", () => {
+      storeCreateEnvironment({ secret: "s1", username: "alice" });
+      storeCreateEnvironment({ secret: "s2", username: "bob" });
+      const aliceEnvs = storeListActiveEnvironmentsByUsername("alice");
+      expect(aliceEnvs).toHaveLength(1);
+      expect(aliceEnvs[0].username).toBe("alice");
+    });
+  });
+
+  // ---------- Session ----------
+
+  describe("storeCreateSession", () => {
+    test("creates session with defaults", () => {
+      const session = storeCreateSession({});
+      expect(session.id).toMatch(/^session_/);
+      expect(session.status).toBe("idle");
+      expect(session.source).toBe("remote-control");
+      expect(session.environmentId).toBeNull();
+      expect(session.workerEpoch).toBe(0);
+    });
+
+    test("creates session with options", () => {
+      const env = storeCreateEnvironment({ secret: "s" });
+      const session = storeCreateSession({
+        environmentId: env.id,
+        title: "Test Session",
+        source: "cli",
+        permissionMode: "auto",
+        username: "alice",
+      });
+      expect(session.environmentId).toBe(env.id);
+      expect(session.title).toBe("Test Session");
+      expect(session.source).toBe("cli");
+      expect(session.permissionMode).toBe("auto");
+      expect(session.username).toBe("alice");
+    });
+
+    test("creates session with custom idPrefix", () => {
+      const session = storeCreateSession({ idPrefix: "cse_" });
+      expect(session.id).toMatch(/^cse_/);
+    });
+  });
+
+  describe("storeGetSession", () => {
+    test("returns undefined for non-existent session", () => {
+      expect(storeGetSession("nope")).toBeUndefined();
+    });
+  });
+
+  describe("storeUpdateSession", () => {
+    test("updates existing session", () => {
+      const session = storeCreateSession({});
+      const result = storeUpdateSession(session.id, { title: "Updated", status: "active" });
+      expect(result).toBe(true);
+      const updated = storeGetSession(session.id);
+      expect(updated?.title).toBe("Updated");
+      expect(updated?.status).toBe("active");
+    });
+
+    test("returns false for non-existent session", () => {
+      expect(storeUpdateSession("nope", { title: "x" })).toBe(false);
+    });
+
+    test("increments workerEpoch", () => {
+      const session = storeCreateSession({});
+      storeUpdateSession(session.id, { workerEpoch: 1 });
+      expect(storeGetSession(session.id)?.workerEpoch).toBe(1);
+    });
+  });
+
+  describe("storeListSessions", () => {
+    test("returns all sessions", () => {
+      storeCreateSession({});
+      storeCreateSession({});
+      expect(storeListSessions()).toHaveLength(2);
+    });
+  });
+
+  describe("storeListSessionsByUsername", () => {
+    test("filters by username", () => {
+      storeCreateSession({ username: "alice" });
+      storeCreateSession({ username: "bob" });
+      expect(storeListSessionsByUsername("alice")).toHaveLength(1);
+    });
+  });
+
+  describe("storeListSessionsByEnvironment", () => {
+    test("filters by environment", () => {
+      const env = storeCreateEnvironment({ secret: "s" });
+      storeCreateSession({ environmentId: env.id });
+      storeCreateSession({});
+      expect(storeListSessionsByEnvironment(env.id)).toHaveLength(1);
+    });
+  });
+
+  describe("storeDeleteSession", () => {
+    test("deletes existing session", () => {
+      const session = storeCreateSession({});
+      expect(storeDeleteSession(session.id)).toBe(true);
+      expect(storeGetSession(session.id)).toBeUndefined();
+    });
+
+    test("returns false for non-existent session", () => {
+      expect(storeDeleteSession("nope")).toBe(false);
+    });
+  });
+
+  // ---------- Session Ownership ----------
+
+  describe("storeBindSession / storeIsSessionOwner", () => {
+    test("binds and checks ownership", () => {
+      const session = storeCreateSession({});
+      storeBindSession(session.id, "uuid-1");
+      expect(storeIsSessionOwner(session.id, "uuid-1")).toBe(true);
+      expect(storeIsSessionOwner(session.id, "uuid-2")).toBe(false);
+    });
+
+    test("unbound session has no owner", () => {
+      const session = storeCreateSession({});
+      expect(storeIsSessionOwner(session.id, "uuid-1")).toBe(false);
+    });
+
+    test("multiple owners per session", () => {
+      const session = storeCreateSession({});
+      storeBindSession(session.id, "uuid-1");
+      storeBindSession(session.id, "uuid-2");
+      expect(storeIsSessionOwner(session.id, "uuid-1")).toBe(true);
+      expect(storeIsSessionOwner(session.id, "uuid-2")).toBe(true);
+    });
+  });
+
+  describe("storeListSessionsByOwnerUuid", () => {
+    test("returns sessions owned by uuid", () => {
+      const s1 = storeCreateSession({});
+      const s2 = storeCreateSession({});
+      storeBindSession(s1.id, "uuid-1");
+      storeBindSession(s2.id, "uuid-1");
+      const owned = storeListSessionsByOwnerUuid("uuid-1");
+      expect(owned).toHaveLength(2);
+    });
+
+    test("returns empty for unknown uuid", () => {
+      expect(storeListSessionsByOwnerUuid("nope")).toHaveLength(0);
+    });
+
+    test("excludes deleted sessions", () => {
+      const s1 = storeCreateSession({});
+      storeBindSession(s1.id, "uuid-1");
+      storeDeleteSession(s1.id);
+      expect(storeListSessionsByOwnerUuid("uuid-1")).toHaveLength(0);
+    });
+  });
+
+  // ---------- Work Items ----------
+
+  describe("storeCreateWorkItem", () => {
+    test("creates work item with defaults", () => {
+      const item = storeCreateWorkItem({
+        environmentId: "env1",
+        sessionId: "ses1",
+        secret: "sec1",
+      });
+      expect(item.id).toMatch(/^work_/);
+      expect(item.environmentId).toBe("env1");
+      expect(item.sessionId).toBe("ses1");
+      expect(item.state).toBe("pending");
+      expect(item.secret).toBe("sec1");
+    });
+  });
+
+  describe("storeGetWorkItem", () => {
+    test("returns undefined for non-existent", () => {
+      expect(storeGetWorkItem("nope")).toBeUndefined();
+    });
+
+    test("returns created work item", () => {
+      const item = storeCreateWorkItem({ environmentId: "env1", sessionId: "ses1", secret: "s" });
+      expect(storeGetWorkItem(item.id)).toBe(item);
+    });
+  });
+
+  describe("storeGetPendingWorkItem", () => {
+    test("returns pending work for environment", () => {
+      const item = storeCreateWorkItem({ environmentId: "env1", sessionId: "ses1", secret: "s" });
+      const found = storeGetPendingWorkItem("env1");
+      expect(found?.id).toBe(item.id);
+    });
+
+    test("returns undefined when no pending work", () => {
+      storeCreateWorkItem({ environmentId: "env1", sessionId: "ses1", secret: "s" });
+      expect(storeGetPendingWorkItem("env2")).toBeUndefined();
+    });
+
+    test("skips non-pending items", () => {
+      const item = storeCreateWorkItem({ environmentId: "env1", sessionId: "ses1", secret: "s" });
+      storeUpdateWorkItem(item.id, { state: "dispatched" });
+      expect(storeGetPendingWorkItem("env1")).toBeUndefined();
+    });
+  });
+
+  describe("storeUpdateWorkItem", () => {
+    test("updates existing work item", () => {
+      const item = storeCreateWorkItem({ environmentId: "env1", sessionId: "ses1", secret: "s" });
+      expect(storeUpdateWorkItem(item.id, { state: "acked" })).toBe(true);
+      expect(storeGetWorkItem(item.id)?.state).toBe("acked");
+    });
+
+    test("returns false for non-existent", () => {
+      expect(storeUpdateWorkItem("nope", { state: "acked" })).toBe(false);
+    });
+  });
+
+  // ---------- storeReset ----------
+
+  describe("storeReset", () => {
+    test("clears all data", () => {
+      storeCreateUser("alice");
+      storeCreateEnvironment({ secret: "s" });
+      storeCreateSession({});
+      storeCreateWorkItem({ environmentId: "env1", sessionId: "ses1", secret: "s" });
+
+      storeReset();
+
+      expect(storeGetUser("alice")).toBeUndefined();
+      expect(storeListActiveEnvironments()).toHaveLength(0);
+      expect(storeListSessions()).toHaveLength(0);
+      expect(storeGetPendingWorkItem("env1")).toBeUndefined();
+    });
+  });
+});

packages/remote-control-server/src/__tests__/work-dispatch.test.ts

@@ -0,0 +1,156 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+// Mock config before imports
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 1, // Short timeout for tests
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { storeReset, storeCreateEnvironment, storeCreateSession, storeGetWorkItem, storeGetPendingWorkItem } from "../store";
+import {
+  createWorkItem,
+  pollWork,
+  ackWork,
+  stopWork,
+  heartbeatWork,
+  reconnectWorkForEnvironment,
+} from "../services/work-dispatch";
+
+describe("Work Dispatch", () => {
+  let envId: string;
+  let sessionId: string;
+
+  beforeEach(() => {
+    storeReset();
+    const env = storeCreateEnvironment({ secret: "s" });
+    envId = env.id;
+    const session = storeCreateSession({ environmentId: envId });
+    sessionId = session.id;
+  });
+
+  describe("createWorkItem", () => {
+    test("creates work item for active environment", async () => {
+      const workId = await createWorkItem(envId, sessionId);
+      expect(workId).toMatch(/^work_/);
+      const item = storeGetWorkItem(workId);
+      expect(item?.state).toBe("pending");
+      expect(item?.sessionId).toBe(sessionId);
+    });
+
+    test("throws for non-existent environment", async () => {
+      await expect(createWorkItem("env_no", sessionId)).rejects.toThrow("not found");
+    });
+
+    test("throws for inactive environment", async () => {
+      const inactiveEnv = storeCreateEnvironment({ secret: "s2" });
+      // Manually set status to deregistered
+      const { storeUpdateEnvironment } = await import("../store");
+      storeUpdateEnvironment(inactiveEnv.id, { status: "deregistered" });
+      await expect(createWorkItem(inactiveEnv.id, sessionId)).rejects.toThrow("not active");
+    });
+
+    test("encodes work secret as base64 JSON", async () => {
+      const workId = await createWorkItem(envId, sessionId);
+      const item = storeGetWorkItem(workId);
+      const decoded = JSON.parse(Buffer.from(item!.secret, "base64url").toString());
+      expect(decoded.version).toBe(1);
+      expect(decoded.session_ingress_token).toBe("test-api-key");
+      expect(decoded.api_base_url).toBe("http://localhost:3000");
+    });
+  });
+
+  describe("pollWork", () => {
+    test("returns null when no work available (timeout)", async () => {
+      const result = await pollWork(envId, 0.1);
+      expect(result).toBeNull();
+    });
+
+    test("returns pending work and marks as dispatched", async () => {
+      const workId = await createWorkItem(envId, sessionId);
+      const result = await pollWork(envId, 1);
+      expect(result).not.toBeNull();
+      expect(result!.id).toBe(workId);
+      expect(result!.state).toBe("dispatched");
+      expect(result!.data.type).toBe("session");
+      expect(result!.data.id).toBe(sessionId);
+      // Work should no longer be pending
+      expect(storeGetPendingWorkItem(envId)).toBeUndefined();
+    });
+
+    test("does not return work for different environment", async () => {
+      const env2 = storeCreateEnvironment({ secret: "s2" });
+      await createWorkItem(envId, sessionId);
+      const result = await pollWork(env2.id, 0.1);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("ackWork", () => {
+    test("marks work as acked", async () => {
+      const workId = await createWorkItem(envId, sessionId);
+      ackWork(workId);
+      expect(storeGetWorkItem(workId)?.state).toBe("acked");
+    });
+  });
+
+  describe("stopWork", () => {
+    test("marks work as completed", async () => {
+      const workId = await createWorkItem(envId, sessionId);
+      stopWork(workId);
+      expect(storeGetWorkItem(workId)?.state).toBe("completed");
+    });
+  });
+
+  describe("heartbeatWork", () => {
+    test("extends lease and returns heartbeat info", async () => {
+      const workId = await createWorkItem(envId, sessionId);
+      const result = heartbeatWork(workId);
+      expect(result.lease_extended).toBe(true);
+      expect(result.ttl_seconds).toBe(40); // heartbeatInterval * 2
+      expect(result.last_heartbeat).toBeTruthy();
+    });
+
+    test("returns default state for non-existent work", async () => {
+      const result = heartbeatWork("work_no");
+      expect(result.state).toBe("acked");
+    });
+  });
+
+  describe("reconnectWorkForEnvironment", () => {
+    test("creates work items for idle sessions in environment", async () => {
+      // Create another idle session
+      storeCreateSession({ environmentId: envId });
+      const workIds = await reconnectWorkForEnvironment(envId);
+      expect(workIds).toHaveLength(2);
+      for (const id of workIds) {
+        expect(storeGetWorkItem(id)?.state).toBe("pending");
+      }
+    });
+
+    test("skips non-idle sessions", async () => {
+      const activeSession = storeCreateSession({ environmentId: envId });
+      const { storeUpdateSession } = await import("../store");
+      storeUpdateSession(activeSession.id, { status: "active" });
+      const workIds = await reconnectWorkForEnvironment(envId);
+      // Only the original idle session should get work
+      expect(workIds).toHaveLength(1);
+    });
+
+    test("returns empty for environment with no sessions", async () => {
+      const emptyEnv = storeCreateEnvironment({ secret: "s_empty" });
+      const workIds = await reconnectWorkForEnvironment(emptyEnv.id);
+      expect(workIds).toHaveLength(0);
+    });
+  });
+});

packages/remote-control-server/src/__tests__/ws-handler.test.ts

@@ -0,0 +1,484 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+// Mock config before imports
+const mockConfig = {
+  port: 3000,
+  host: "0.0.0.0",
+  apiKeys: ["test-api-key"],
+  baseUrl: "http://localhost:3000",
+  pollTimeout: 8,
+  heartbeatInterval: 20,
+  jwtExpiresIn: 3600,
+  disconnectTimeout: 300,
+};
+
+mock.module("../config", () => ({
+  config: mockConfig,
+  getBaseUrl: () => "http://localhost:3000",
+}));
+
+import { storeReset } from "../store";
+import { getEventBus, removeEventBus, getAllEventBuses } from "../transport/event-bus";
+import {
+  ingestBridgeMessage,
+  handleWebSocketOpen,
+  handleWebSocketMessage,
+  handleWebSocketClose,
+  closeAllConnections,
+} from "../transport/ws-handler";
+
+// Minimal WSContext mock
+function createMockWs(readyState = 1) {
+  const sent: string[] = [];
+  return {
+    readyState,
+    send: (data: string) => sent.push(data),
+    close: (_code?: number, _reason?: string) => {},
+    getSentData: () => sent,
+  } as any;
+}
+
+describe("ws-handler", () => {
+  beforeEach(() => {
+    storeReset();
+    for (const [key] of getAllEventBuses()) {
+      removeEventBus(key);
+    }
+    closeAllConnections();
+  });
+
+  describe("ingestBridgeMessage", () => {
+    test("ignores keep_alive messages", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", { type: "keep_alive" });
+      expect(events).toHaveLength(0);
+    });
+
+    test("derives type from message.role for user messages", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", {
+        message: { role: "user", content: "hello" },
+        uuid: "u1",
+      });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("user");
+      expect((events[0] as any).direction).toBe("inbound");
+    });
+
+    test("derives type from message.role for assistant messages", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", {
+        message: { role: "assistant", content: [{ type: "text", text: "response" }] },
+        uuid: "u2",
+      });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("assistant");
+      const payload = (events[0] as any).payload as Record<string, unknown>;
+      expect(payload.content).toBe("response");
+    });
+
+    test("derives type from explicit type field", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", { type: "control_request", request_id: "r1", request: { subtype: "interrupt" } });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("control_request");
+    });
+
+    test("derives result type from subtype/result fields", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", { subtype: "success", uuid: "u3", result: "done" });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("result");
+    });
+
+    test("derives system type from session_id field", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", { session_id: "s1", init: true });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("system");
+    });
+
+    test("handles control_response type", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", {
+        type: "control_response",
+        response: { subtype: "success" },
+      });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("control_response");
+    });
+
+    test("handles partial_assistant type", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", {
+        type: "partial_assistant",
+        message: { content: "partial..." },
+        uuid: "u4",
+      });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("partial_assistant");
+    });
+
+    test("falls back to unknown type", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+      ingestBridgeMessage("s1", { data: "something" });
+      expect(events).toHaveLength(1);
+      expect((events[0] as any).type).toBe("unknown");
+    });
+  });
+
+  describe("handleWebSocketOpen", () => {
+    test("subscribes to event bus and replays missed events", () => {
+      // Publish some events before WS connects
+      const bus = getEventBus("s1");
+      bus.publish({ id: "e1", sessionId: "s1", type: "user", payload: { content: "hello" }, direction: "outbound" });
+      bus.publish({ id: "e2", sessionId: "s1", type: "assistant", payload: { content: "hi" }, direction: "inbound" });
+
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "s1");
+
+      // Should have replayed the outbound event (only outbound events are forwarded to WS)
+      const sent = ws.getSentData();
+      expect(sent.length).toBeGreaterThanOrEqual(1);
+      // First message should be the outbound user event
+      const msg = JSON.parse(sent[0]);
+      expect(msg.type).toBe("user");
+    });
+
+    test("replaces existing connection for same session", () => {
+      const ws1 = createMockWs();
+      const ws2 = createMockWs();
+      handleWebSocketOpen(ws1, "s2");
+      handleWebSocketOpen(ws2, "s2");
+
+      // ws2 should be the active connection
+      const bus = getEventBus("s2");
+      bus.publish({ id: "e1", sessionId: "s2", type: "user", payload: { content: "test" }, direction: "outbound" });
+      expect(ws2.getSentData().length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe("handleWebSocketMessage", () => {
+    test("parses NDJSON and ingests each message", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+
+      const ws = createMockWs();
+      const data = JSON.stringify({ type: "user", message: { role: "user", content: "hello" } }) + "\n" +
+        JSON.stringify({ type: "assistant", message: { role: "assistant", content: "hi" } }) + "\n";
+      handleWebSocketMessage(ws, "s1", data);
+      expect(events).toHaveLength(2);
+    });
+
+    test("ignores malformed JSON lines", () => {
+      const bus = getEventBus("s1");
+      const events: unknown[] = [];
+      bus.subscribe((e) => events.push(e));
+
+      const ws = createMockWs();
+      handleWebSocketMessage(ws, "s1", "not json\n");
+      expect(events).toHaveLength(0);
+    });
+  });
+
+  describe("handleWebSocketClose", () => {
+    test("cleans up on close", () => {
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "s3");
+      handleWebSocketClose(ws, "s3", 1000, "done");
+
+      // After close, publishing events should not cause errors
+      const bus = getEventBus("s3");
+      expect(() =>
+        bus.publish({ id: "e1", sessionId: "s3", type: "user", payload: {}, direction: "outbound" })
+      ).not.toThrow();
+    });
+  });
+
+  describe("toSDKMessage (via handleWebSocketOpen outbound delivery)", () => {
+    test("converts permission_response with approved=true", () => {
+      const bus = getEventBus("pr1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "pr1");
+
+      bus.publish({
+        id: "e1",
+        sessionId: "pr1",
+        type: "permission_response",
+        payload: { approved: true, request_id: "req1" },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_response");
+      expect(lastMsg.response.subtype).toBe("success");
+      expect(lastMsg.response.request_id).toBe("req1");
+      expect(lastMsg.response.response.behavior).toBe("allow");
+    });
+
+    test("converts permission_response with approved=false", () => {
+      const bus = getEventBus("pr2");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "pr2");
+
+      bus.publish({
+        id: "e2",
+        sessionId: "pr2",
+        type: "permission_response",
+        payload: { approved: false, request_id: "req2" },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_response");
+      expect(lastMsg.response.subtype).toBe("error");
+      expect(lastMsg.response.error).toBe("Permission denied by user");
+      expect(lastMsg.response.response.behavior).toBe("deny");
+    });
+
+    test("converts permission_response with existing response object", () => {
+      const bus = getEventBus("pr3");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "pr3");
+
+      bus.publish({
+        id: "e3",
+        sessionId: "pr3",
+        type: "control_response",
+        payload: { response: { subtype: "success", data: "custom" } },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_response");
+      expect(lastMsg.response.subtype).toBe("success");
+      expect(lastMsg.response.data).toBe("custom");
+    });
+
+    test("converts interrupt event", () => {
+      const bus = getEventBus("int1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "int1");
+
+      bus.publish({
+        id: "e4",
+        sessionId: "int1",
+        type: "interrupt",
+        payload: { action: "interrupt" },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_request");
+      expect(lastMsg.request_id).toBe("e4");
+      expect(lastMsg.request.subtype).toBe("interrupt");
+    });
+
+    test("converts control_request event", () => {
+      const bus = getEventBus("cr1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "cr1");
+
+      bus.publish({
+        id: "e5",
+        sessionId: "cr1",
+        type: "control_request",
+        payload: { request_id: "req5", request: { subtype: "permission", tool_name: "Bash" } },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_request");
+      expect(lastMsg.request_id).toBe("req5");
+      expect(lastMsg.request.subtype).toBe("permission");
+    });
+
+    test("converts user_message event type", () => {
+      const bus = getEventBus("um1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "um1");
+
+      bus.publish({
+        id: "e6",
+        sessionId: "um1",
+        type: "user_message",
+        payload: { content: "hello world" },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("user");
+      expect(lastMsg.message.content).toBe("hello world");
+    });
+
+    test("converts generic event type", () => {
+      const bus = getEventBus("gen1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "gen1");
+
+      bus.publish({
+        id: "e7",
+        sessionId: "gen1",
+        type: "status",
+        payload: { state: "running" },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("status");
+      expect(lastMsg.message).toEqual({ state: "running" });
+    });
+
+    test("permission_response with updated_input", () => {
+      const bus = getEventBus("ui1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "ui1");
+
+      bus.publish({
+        id: "e8",
+        sessionId: "ui1",
+        type: "permission_response",
+        payload: { approved: true, request_id: "req8", updated_input: { cmd: "ls -la" } },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.response.response.behavior).toBe("allow");
+      expect(lastMsg.response.response.updatedInput).toEqual({ cmd: "ls -la" });
+    });
+
+    test("permission_response with updated_permissions", () => {
+      const bus = getEventBus("up1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "up1");
+
+      const permissions = [{ type: "setMode", mode: "acceptEdits", destination: "session" }];
+      bus.publish({
+        id: "ep1",
+        sessionId: "up1",
+        type: "permission_response",
+        payload: {
+          approved: true,
+          request_id: "req-ep1",
+          updated_input: { plan: "my plan" },
+          updated_permissions: permissions,
+        },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_response");
+      expect(lastMsg.response.subtype).toBe("success");
+      expect(lastMsg.response.response.behavior).toBe("allow");
+      expect(lastMsg.response.response.updatedInput).toEqual({ plan: "my plan" });
+      expect(lastMsg.response.response.updatedPermissions).toEqual(permissions);
+    });
+
+    test("permission_response denied with feedback message", () => {
+      const bus = getEventBus("dm1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "dm1");
+
+      bus.publish({
+        id: "dm1",
+        sessionId: "dm1",
+        type: "permission_response",
+        payload: {
+          approved: false,
+          request_id: "req-dm1",
+          message: "Please add more tests",
+        },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_response");
+      expect(lastMsg.response.subtype).toBe("error");
+      expect(lastMsg.response.response.behavior).toBe("deny");
+      expect(lastMsg.response.message).toBe("Please add more tests");
+    });
+
+    test("does not forward inbound events to WS", () => {
+      const bus = getEventBus("no_in");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "no_in");
+
+      bus.publish({
+        id: "e9",
+        sessionId: "no_in",
+        type: "assistant",
+        payload: { content: "reply" },
+        direction: "inbound",
+      });
+
+      // Only replayed events, no new inbound delivery
+      const sent = ws.getSentData();
+      // No outbound events were published, so only replay (if any)
+      // Since the bus was fresh, no replay
+      expect(sent).toHaveLength(0);
+    });
+
+    test("control_request falls back to payload when no request field", () => {
+      const bus = getEventBus("cf1");
+      const ws = createMockWs();
+      handleWebSocketOpen(ws, "cf1");
+
+      bus.publish({
+        id: "e10",
+        sessionId: "cf1",
+        type: "control_request",
+        payload: { request_id: "req10", subtype: "custom", data: "test" },
+        direction: "outbound",
+      });
+
+      const sent = ws.getSentData();
+      const lastMsg = JSON.parse(sent[sent.length - 1]);
+      expect(lastMsg.type).toBe("control_request");
+      expect(lastMsg.request_id).toBe("req10");
+    });
+  });
+
+  describe("closeAllConnections", () => {
+    test("closes all active connections", () => {
+      const ws1 = createMockWs();
+      const ws2 = createMockWs();
+      handleWebSocketOpen(ws1, "s1");
+      handleWebSocketOpen(ws2, "s2");
+      closeAllConnections();
+      // No errors thrown
+    });
+
+    test("no-op when no connections", () => {
+      expect(() => closeAllConnections()).not.toThrow();
+    });
+  });
+});

packages/remote-control-server/src/auth/api-key.ts

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+import { config } from "../config";
+
+/** Validate a raw API key token string */
+export function validateApiKey(token: string | undefined): boolean {
+  if (!token) return false;
+  return config.apiKeys.includes(token);
+}
+
+export function hashApiKey(key: string): string {
+  return createHash("sha256").update(key).digest("hex");
+}

packages/remote-control-server/src/auth/jwt.ts

@@ -0,0 +1,92 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Lightweight JWT implementation using HMAC-SHA256.
+ * No external dependencies — uses Node.js crypto.
+ *
+ * Token format: base64url(header).base64url(payload).base64url(signature)
+ * Used for V2 worker authentication (session ingress / SSE / CCR).
+ */
+
+interface JwtPayload {
+  session_id: string;
+  role: string;
+  iat: number;
+  exp: number;
+}
+
+function base64url(data: string | Buffer): string {
+  return Buffer.from(data as unknown as ArrayLike<number>)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function base64urlDecode(str: string): string {
+  const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(padded, "base64").toString("utf-8");
+}
+
+function getSigningKey(): string {
+  const key = process.env.RCS_API_KEYS?.split(",").filter(Boolean)[0];
+  if (!key) throw new Error("No API key configured for JWT signing");
+  return key;
+}
+
+/** Generate a JWT for worker authentication. */
+export function generateWorkerJwt(
+  sessionId: string,
+  expiresInSeconds: number,
+): string {
+  const header = { alg: "HS256", typ: "JWT" };
+  const payload: JwtPayload = {
+    session_id: sessionId,
+    role: "worker",
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + expiresInSeconds,
+  };
+
+  const headerB64 = base64url(JSON.stringify(header));
+  const payloadB64 = base64url(JSON.stringify(payload));
+  const signingInput = `${headerB64}.${payloadB64}`;
+
+  const signature = createHmac("sha256", getSigningKey())
+    .update(signingInput)
+    .digest();
+
+  return `${signingInput}.${base64url(signature)}`;
+}
+
+/**
+ * Verify a JWT and return its payload, or null if invalid/expired.
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+export function verifyWorkerJwt(token: string): JwtPayload | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // Verify signature
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const expectedSig = createHmac("sha256", getSigningKey())
+    .update(signingInput)
+    .digest();
+  const actualSig = Buffer.from(
+    signatureB64.replace(/-/g, "+").replace(/_/g, "/"),
+    "base64",
+  );
+
+  if (expectedSig.length !== actualSig.length) return null;
+  if (!timingSafeEqual(expectedSig, actualSig)) return null;
+
+  // Decode payload
+  try {
+    const payload: JwtPayload = JSON.parse(base64urlDecode(payloadB64));
+    if (payload.exp < Math.floor(Date.now() / 1000)) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}

packages/remote-control-server/src/auth/middleware.ts

@@ -0,0 +1,102 @@
+import type { Context, Next } from "hono";
+import { validateApiKey } from "./api-key";
+import { verifyWorkerJwt } from "./jwt";
+import { resolveToken } from "./token";
+
+/** Extract Bearer token from Authorization header or ?token= query param */
+function extractBearerToken(c: Context): string | undefined {
+  const authHeader = c.req.header("Authorization");
+  const queryToken = c.req.query("token");
+  return authHeader?.replace("Bearer ", "") || queryToken;
+}
+
+/**
+ * Unified authentication middleware — supports two modes:
+ *
+ * 1. **Token mode** (Web UI): Bearer token resolved via server-side lookup → username injected
+ * 2. **API Key mode** (CLI bridge): Valid API key + X-Username header → username injected
+ */
+export async function apiKeyAuth(c: Context, next: Next) {
+  const token = extractBearerToken(c);
+
+  // Try token authentication (Web UI)
+  const tokenUsername = resolveToken(token);
+  if (tokenUsername) {
+    c.set("username", tokenUsername);
+    await next();
+    return;
+  }
+
+  // Try API Key authentication (CLI bridge)
+  if (validateApiKey(token)) {
+    // Extract username from X-Username header or ?username= query param
+    const username = c.req.header("X-Username") || c.req.query("username");
+    if (username) {
+      c.set("username", username);
+    }
+    await next();
+    return;
+  }
+
+  return c.json({ error: { type: "unauthorized", message: "Invalid or missing auth token" } }, 401);
+}
+
+/**
+ * Session ingress authentication — accepts both API key and worker JWT.
+ *
+ * Used for SSE stream, CCR worker events, and WebSocket ingress endpoints.
+ * On JWT validation, stores the decoded payload in c.set("jwtPayload") for
+ * downstream handlers to inspect session_id if needed.
+ */
+export async function sessionIngressAuth(c: Context, next: Next) {
+  const token = extractBearerToken(c);
+
+  if (!token) {
+    return c.json({ error: { type: "unauthorized", message: "Missing auth token" } }, 401);
+  }
+
+  // Try API key first (backward compatible)
+  if (validateApiKey(token)) {
+    await next();
+    return;
+  }
+
+  // Try JWT verification — validate session_id matches route param
+  const payload = verifyWorkerJwt(token);
+  if (payload) {
+    const routeSessionId = c.req.param("id") || c.req.param("sessionId");
+    if (routeSessionId && payload.session_id !== routeSessionId) {
+      return c.json({ error: { type: "forbidden", message: "JWT session_id does not match target session" } }, 403);
+    }
+    c.set("jwtPayload", payload);
+    await next();
+    return;
+  }
+
+  return c.json({ error: { type: "unauthorized", message: "Invalid API key or JWT" } }, 401);
+}
+
+/** Accept CLI headers but don't validate them */
+export async function acceptCliHeaders(c: Context, next: Next) {
+  await next();
+}
+
+/**
+ * Extract UUID from request — query param ?uuid= or header X-UUID
+ */
+export function getUuidFromRequest(c: Context): string | undefined {
+  return c.req.query("uuid") || c.req.header("X-UUID");
+}
+
+/**
+ * UUID-based auth for Web UI routes (no-login mode).
+ * Requires a UUID in query param or header, injects it into context as c.set("uuid").
+ */
+export async function uuidAuth(c: Context, next: Next) {
+  const uuid = getUuidFromRequest(c);
+  if (!uuid) {
+    return c.json({ error: { type: "unauthorized", message: "Missing UUID" } }, 401);
+  }
+  c.set("uuid", uuid);
+  await next();
+}

packages/remote-control-server/src/auth/token.ts

@@ -0,0 +1,24 @@
+import { storeCreateToken, storeGetUserByToken } from "../store";
+
+let tokenCounter = 0;
+
+/** Generate a random session token and associate it with a user */
+export function issueToken(username: string): { token: string; expires_in: number } {
+  // Use crypto.getRandomValues for uniqueness
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  const token = `rct_${tokenCounter++}_${hex}`;
+  storeCreateToken(username, token);
+  return { token, expires_in: 86400 };
+}
+
+/** Resolve a token to a username. Returns null if invalid. */
+export function resolveToken(token: string | undefined): string | null {
+  if (!token) return null;
+  const entry = storeGetUserByToken(token);
+  if (!entry) return null;
+  return entry.username;
+}

packages/remote-control-server/src/config.ts

@@ -0,0 +1,16 @@
+export const config = {
+  version: process.env.RCS_VERSION || "0.1.0",
+  port: parseInt(process.env.RCS_PORT || "3000"),
+  host: process.env.RCS_HOST || "0.0.0.0",
+  apiKeys: (process.env.RCS_API_KEYS || "").split(",").filter(Boolean),
+  baseUrl: process.env.RCS_BASE_URL || "",
+  pollTimeout: parseInt(process.env.RCS_POLL_TIMEOUT || "8"),
+  heartbeatInterval: parseInt(process.env.RCS_HEARTBEAT_INTERVAL || "20"),
+  jwtExpiresIn: parseInt(process.env.RCS_JWT_EXPIRES_IN || "3600"),
+  disconnectTimeout: parseInt(process.env.RCS_DISCONNECT_TIMEOUT || "300"),
+} as const;
+
+export function getBaseUrl(): string {
+  if (config.baseUrl) return config.baseUrl;
+  return `http://localhost:${config.port}`;
+}

packages/remote-control-server/src/index.ts

@@ -0,0 +1,103 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import { serveStatic } from "hono/bun";
+import { config } from "./config";
+import { closeAllConnections } from "./transport/ws-handler";
+import { startDisconnectMonitor } from "./services/disconnect-monitor";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Routes
+import v1Environments from "./routes/v1/environments";
+import v1EnvironmentsWork from "./routes/v1/environments.work";
+import v1Sessions from "./routes/v1/sessions";
+import v1SessionIngress, { websocket } from "./routes/v1/session-ingress";
+import v2CodeSessions from "./routes/v2/code-sessions";
+import v2Worker from "./routes/v2/worker";
+import v2WorkerEventsStream from "./routes/v2/worker-events-stream";
+import v2WorkerEvents from "./routes/v2/worker-events";
+import webAuth from "./routes/web/auth";
+import webSessions from "./routes/web/sessions";
+import webControl from "./routes/web/control";
+import webEnvironments from "./routes/web/environments";
+
+console.log("[RCS] In-memory store ready (no SQLite)");
+
+const app = new Hono();
+
+// Middleware
+app.use("*", logger());
+app.use("/web/*", cors());
+
+// Health check
+app.get("/health", (c) => c.json({ status: "ok", version: config.version }));
+
+// Static files — serve web/ directory under /code path
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const webDir = resolve(__dirname, "../web");
+
+const stripCodePrefix = (p: string) => p.replace(/^\/code/, "");
+
+// Serve all static files under /code/* from web/ directory
+app.use("/code/*", serveStatic({ root: webDir, rewriteRequestPath: stripCodePrefix }));
+// /code, /code/, and /code/:sessionId — SPA fallback
+app.get("/code", serveStatic({ root: webDir, path: "index.html" }));
+app.get("/code/", serveStatic({ root: webDir, path: "index.html" }));
+app.get("/code/:sessionId", serveStatic({ root: webDir, path: "index.html" }));
+
+// v1 Environment routes
+app.route("/v1/environments", v1Environments);
+app.route("/v1/environments", v1EnvironmentsWork);
+
+// v1 Session routes
+app.route("/v1/sessions", v1Sessions);
+
+// Session Ingress (WebSocket) — mounted at both /v1 and /v2 so the bridge
+// client's buildSdkUrl works with or without an Envoy proxy rewriting /v1→/v2.
+app.route("/v1/session_ingress", v1SessionIngress);
+app.route("/v2/session_ingress", v1SessionIngress);
+
+// v2 Code Sessions routes
+app.route("/v1/code/sessions", v2CodeSessions);
+app.route("/v1/code/sessions", v2Worker);
+app.route("/v1/code/sessions", v2WorkerEventsStream);
+app.route("/v1/code/sessions", v2WorkerEvents);
+
+// Web control panel routes
+app.route("/web", webAuth);
+app.route("/web", webSessions);
+app.route("/web", webControl);
+app.route("/web", webEnvironments);
+
+const port = config.port;
+const host = config.host;
+
+console.log(`[RCS] Remote Control Server starting on ${host}:${port}`);
+console.log("[RCS] API key configuration loaded");
+console.log(`[RCS] Base URL: ${config.baseUrl || `http://localhost:${port}`}`);
+console.log(`[RCS] Disconnect timeout: ${config.disconnectTimeout}s`);
+
+// Start disconnect monitor
+startDisconnectMonitor();
+
+export default {
+  port,
+  hostname: host,
+  fetch: app.fetch,
+  websocket: {
+    ...websocket,
+    idleTimeout: 255, // WS idle timeout (seconds) — must be inside websocket object
+  },
+  idleTimeout: 255, // HTTP server idle timeout (seconds) — needed for long-polling endpoints
+};
+
+// Graceful shutdown
+async function gracefulShutdown(signal: string) {
+  console.log(`\n[RCS] Received ${signal}, shutting down...`);
+  closeAllConnections();
+  process.exit(0);
+}
+
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));

packages/remote-control-server/src/routes/v1/environments.ts

@@ -0,0 +1,31 @@
+import { Hono } from "hono";
+import { registerEnvironment, deregisterEnvironment, reconnectEnvironment } from "../../services/environment";
+import { apiKeyAuth, acceptCliHeaders } from "../../auth/middleware";
+
+const app = new Hono();
+
+/** POST /v1/environments/bridge — Register an environment */
+app.post("/bridge", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const body = await c.req.json();
+  const username = c.get("username");
+  const result = registerEnvironment({ ...body, username });
+  return c.json(result, 200);
+});
+
+/** DELETE /v1/environments/bridge/:id — Deregister */
+app.delete("/bridge/:id", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const envId = c.req.param("id");
+  deregisterEnvironment(envId);
+  return c.json({ status: "ok" }, 200);
+});
+
+/** POST /v1/environments/:id/bridge/reconnect — Reconnect */
+app.post("/:id/bridge/reconnect", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const envId = c.req.param("id");
+  reconnectEnvironment(envId);
+  const { reconnectWorkForEnvironment } = await import("../../services/work-dispatch");
+  await reconnectWorkForEnvironment(envId);
+  return c.json({ status: "ok" }, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/v1/environments.work.ts

@@ -0,0 +1,41 @@
+import { Hono } from "hono";
+import { pollWork, ackWork, stopWork, heartbeatWork } from "../../services/work-dispatch";
+import { apiKeyAuth, acceptCliHeaders } from "../../auth/middleware";
+import { updatePollTime } from "../../services/environment";
+
+const app = new Hono();
+
+/** GET /v1/environments/:id/work/poll — Long-poll for work */
+app.get("/:id/work/poll", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const envId = c.req.param("id");
+  updatePollTime(envId);
+  const result = await pollWork(envId);
+  if (!result) {
+    // Return 204 No Content so the client's axios parses it as null
+    return c.body(null, 204);
+  }
+  return c.json(result, 200);
+});
+
+/** POST /v1/environments/:id/work/:workId/ack — Acknowledge work */
+app.post("/:id/work/:workId/ack", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const workId = c.req.param("workId");
+  ackWork(workId);
+  return c.json({ status: "ok" }, 200);
+});
+
+/** POST /v1/environments/:id/work/:workId/stop — Stop work */
+app.post("/:id/work/:workId/stop", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const workId = c.req.param("workId");
+  stopWork(workId);
+  return c.json({ status: "ok" }, 200);
+});
+
+/** POST /v1/environments/:id/work/:workId/heartbeat — Heartbeat */
+app.post("/:id/work/:workId/heartbeat", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const workId = c.req.param("workId");
+  const result = heartbeatWork(workId);
+  return c.json(result, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/v1/session-ingress.ts

@@ -0,0 +1,119 @@
+import { Hono } from "hono";
+import { createBunWebSocket } from "hono/bun";
+import { validateApiKey } from "../../auth/api-key";
+import { verifyWorkerJwt } from "../../auth/jwt";
+import {
+  handleWebSocketOpen,
+  handleWebSocketMessage,
+  handleWebSocketClose,
+  ingestBridgeMessage,
+} from "../../transport/ws-handler";
+import { getSession } from "../../services/session";
+
+const { upgradeWebSocket, websocket } = createBunWebSocket();
+
+const app = new Hono();
+
+/** Authenticate via API key or worker JWT in Authorization header or ?token= query param */
+function authenticateRequest(c: any, label: string, expectedSessionId?: string): boolean {
+  const authHeader = c.req.header("Authorization");
+  const queryToken = c.req.query("token");
+  const token = authHeader?.replace("Bearer ", "") || queryToken;
+
+  // Try API key first
+  if (validateApiKey(token)) {
+    return true;
+  }
+
+  // Try JWT verification — validate session_id matches if provided
+  if (token) {
+    const payload = verifyWorkerJwt(token);
+    if (payload) {
+      if (expectedSessionId && payload.session_id !== expectedSessionId) {
+        console.log(`[Auth] ${label}: FAILED — JWT session_id mismatch`);
+        return false;
+      }
+      return true;
+    }
+  }
+
+  console.log(`[Auth] ${label}: FAILED — no valid API key or JWT`);
+  return false;
+}
+
+/** POST /v2/session_ingress/session/:sessionId/events — HTTP POST (HybridTransport writes) */
+app.post("/session/:sessionId/events", async (c) => {
+  const sessionId = c.req.param("sessionId")!;
+
+  if (!authenticateRequest(c, `POST session/${sessionId}`, sessionId)) {
+    return c.json({ error: { type: "unauthorized", message: "Invalid auth" } }, 401);
+  }
+
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+
+  const body = await c.req.json();
+  const events = Array.isArray(body.events) ? body.events : [body];
+
+  let count = 0;
+  for (const msg of events) {
+    if (!msg || typeof msg !== "object") continue;
+    ingestBridgeMessage(sessionId, msg as Record<string, unknown>);
+    count++;
+  }
+
+  return c.json({ status: "ok" }, 200);
+});
+
+/** WS /v2/session_ingress/ws/:sessionId — WebSocket transport */
+app.get(
+  "/ws/:sessionId",
+  upgradeWebSocket(async (c) => {
+    const sessionId = c.req.param("sessionId")!;
+
+    if (!authenticateRequest(c, `WS ${sessionId}`, sessionId)) {
+      return {
+        onOpen(_evt, ws) {
+          ws.close(4003, "unauthorized");
+        },
+      };
+    }
+
+    const session = getSession(sessionId);
+    if (!session) {
+      console.log(`[WS] Upgrade rejected: session ${sessionId} not found`);
+      return {
+        onOpen(_evt, ws) {
+          ws.close(4001, "session not found");
+        },
+      };
+    }
+
+    console.log(`[WS] Upgrade accepted: session=${sessionId}`);
+    return {
+      onOpen(_evt, ws) {
+        handleWebSocketOpen(ws as any, sessionId);
+      },
+      onMessage(evt, ws) {
+        const data =
+          typeof evt.data === "string"
+            ? evt.data
+            : new TextDecoder().decode(evt.data as ArrayBuffer);
+        handleWebSocketMessage(ws as any, sessionId, data);
+      },
+      onClose(evt, ws) {
+        const closeEvt = evt as unknown as CloseEvent;
+        handleWebSocketClose(ws as any, sessionId, closeEvt?.code, closeEvt?.reason);
+      },
+      onError(evt, ws) {
+        console.error(`[WS] Error on session=${sessionId}:`, evt);
+        handleWebSocketClose(ws as any, sessionId, 1006, "websocket error");
+      },
+    };
+  }),
+);
+
+export { websocket };
+export default app;

packages/remote-control-server/src/routes/v1/sessions.ts

@@ -0,0 +1,85 @@
+import { Hono } from "hono";
+import {
+  createSession,
+  getSession,
+  updateSessionTitle,
+  archiveSession,
+} from "../../services/session";
+import { createWorkItem } from "../../services/work-dispatch";
+import { apiKeyAuth, acceptCliHeaders } from "../../auth/middleware";
+import { publishSessionEvent } from "../../services/transport";
+
+const app = new Hono();
+
+/** POST /v1/sessions — Create session */
+app.post("/", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const body = await c.req.json();
+  const username = c.get("username");
+  const session = createSession({ ...body, username });
+
+  // Create work item if environment is specified
+  if (body.environment_id) {
+    try {
+      await createWorkItem(body.environment_id, session.id);
+    } catch (err) {
+      console.error(`[RCS] Failed to create work item: ${(err as Error).message}`);
+    }
+  }
+
+  // Publish initial events if provided
+  if (body.events && Array.isArray(body.events)) {
+    for (const evt of body.events) {
+      publishSessionEvent(session.id, evt.type || "init", evt, "outbound");
+    }
+  }
+
+  return c.json(session, 200);
+});
+
+/** GET /v1/sessions/:id — Get session */
+app.get("/:id", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const session = getSession(c.req.param("id"));
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+  return c.json(session, 200);
+});
+
+/** PATCH /v1/sessions/:id — Update session title */
+app.patch("/:id", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const body = await c.req.json();
+  if (body.title) {
+    updateSessionTitle(c.req.param("id"), body.title);
+  }
+  const session = getSession(c.req.param("id"));
+  return c.json(session, 200);
+});
+
+/** POST /v1/sessions/:id/archive — Archive session */
+app.post("/:id/archive", acceptCliHeaders, apiKeyAuth, async (c) => {
+  try {
+    archiveSession(c.req.param("id"));
+  } catch {
+    return c.json({ status: "ok" }, 409);
+  }
+  return c.json({ status: "ok" }, 200);
+});
+
+/** POST /v1/sessions/:id/events — Send event to session */
+app.post("/:id/events", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const sessionId = c.req.param("id");
+  const body = await c.req.json();
+
+  const events = body.events
+    ? Array.isArray(body.events) ? body.events : [body.events]
+    : Array.isArray(body) ? body : [body];
+  const published = [];
+  for (const evt of events) {
+    const result = publishSessionEvent(sessionId, evt.type || "message", evt, "inbound");
+    published.push(result);
+  }
+
+  return c.json({ status: "ok", events: published.length }, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/v2/code-sessions.ts

@@ -0,0 +1,36 @@
+import { Hono } from "hono";
+import { createCodeSession, getSession, incrementEpoch } from "../../services/session";
+import { apiKeyAuth, acceptCliHeaders } from "../../auth/middleware";
+import { generateWorkerJwt } from "../../auth/jwt";
+import { getBaseUrl, config } from "../../config";
+
+const app = new Hono();
+
+/** POST /v1/code/sessions — Create code session (wrapped response for TUI compat) */
+app.post("/", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const body = await c.req.json();
+  const session = createCodeSession(body);
+  return c.json({ session }, 200);
+});
+
+/** POST /v1/code/sessions/:id/bridge — Get connection info + worker JWT */
+app.post("/:id/bridge", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const sessionId = c.req.param("id");
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+
+  const epoch = incrementEpoch(sessionId);
+  const expiresInSeconds = config.jwtExpiresIn;
+  const workerJwt = generateWorkerJwt(sessionId, expiresInSeconds);
+
+  return c.json({
+    api_base_url: getBaseUrl(),
+    worker_epoch: epoch,
+    worker_jwt: workerJwt,
+    expires_in: expiresInSeconds,
+  }, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/v2/worker-events-stream.ts

@@ -0,0 +1,24 @@
+import { Hono } from "hono";
+import { sessionIngressAuth, acceptCliHeaders } from "../../auth/middleware";
+import { createSSEStream } from "../../transport/sse-writer";
+import { getSession } from "../../services/session";
+
+const app = new Hono();
+
+/** SSE /v1/code/sessions/:id/worker/events/stream — SSE event stream */
+app.get("/:id/worker/events/stream", acceptCliHeaders, sessionIngressAuth, async (c) => {
+  const sessionId = c.req.param("id");
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+
+  // Support Last-Event-ID / from_sequence_num for reconnection
+  const lastEventId = c.req.header("Last-Event-ID");
+  const fromSeq = c.req.query("from_sequence_num");
+  const fromSeqNum = fromSeq ? parseInt(fromSeq) : lastEventId ? parseInt(lastEventId) : 0;
+
+  return createSSEStream(c, sessionId, fromSeqNum);
+});
+
+export default app;

packages/remote-control-server/src/routes/v2/worker-events.ts

@@ -0,0 +1,48 @@
+import { Hono } from "hono";
+import { sessionIngressAuth, acceptCliHeaders } from "../../auth/middleware";
+import { publishSessionEvent } from "../../services/transport";
+import { getSession, updateSessionStatus } from "../../services/session";
+
+const app = new Hono();
+
+/** POST /v1/code/sessions/:id/worker/events — Write events */
+app.post("/:id/worker/events", acceptCliHeaders, sessionIngressAuth, async (c) => {
+  const sessionId = c.req.param("id");
+  const body = await c.req.json();
+
+  const events = Array.isArray(body) ? body : [body];
+  const published = [];
+  for (const evt of events) {
+    const result = publishSessionEvent(sessionId, evt.type || "message", evt, "inbound");
+    published.push(result);
+  }
+
+  return c.json({ status: "ok", count: published.length }, 200);
+});
+
+/** PUT /v1/code/sessions/:id/worker/state — Report worker state */
+app.put("/:id/worker/state", acceptCliHeaders, sessionIngressAuth, async (c) => {
+  const sessionId = c.req.param("id");
+  const body = await c.req.json();
+
+  if (body.status) {
+    updateSessionStatus(sessionId, body.status);
+  }
+
+  return c.json({ status: "ok" }, 200);
+});
+
+/** PUT /v1/code/sessions/:id/worker/external_metadata — Report worker metadata (no-op) */
+app.put("/:id/worker/external_metadata", acceptCliHeaders, sessionIngressAuth, async (c) => {
+  // TUI's CCRClient calls this for metadata reporting. Accept and discard.
+  return c.json({ status: "ok" }, 200);
+});
+
+/** POST /v1/code/sessions/:id/worker/events/:eventId/delivery — Delivery tracking (no-op) */
+app.post("/:id/worker/events/:eventId/delivery", acceptCliHeaders, sessionIngressAuth, async (c) => {
+  // TUI's CCRClient reports event delivery status (received/processing/processed).
+  // Accept and discard — event bus doesn't track per-event delivery.
+  return c.json({ status: "ok" }, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/v2/worker.ts

@@ -0,0 +1,19 @@
+import { Hono } from "hono";
+import { getSession, incrementEpoch } from "../../services/session";
+import { apiKeyAuth, acceptCliHeaders } from "../../auth/middleware";
+
+const app = new Hono();
+
+/** POST /v1/code/sessions/:id/worker/register — Register worker */
+app.post("/:id/worker/register", acceptCliHeaders, apiKeyAuth, async (c) => {
+  const sessionId = c.req.param("id");
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+
+  const epoch = incrementEpoch(sessionId);
+  return c.json({ worker_epoch: epoch }, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/web/auth.ts

@@ -0,0 +1,26 @@
+import { Hono } from "hono";
+import { storeGetSession, storeBindSession } from "../../store";
+
+const app = new Hono();
+
+/** POST /web/bind — Bind a session to a UUID (no-login auth) */
+app.post("/bind", async (c) => {
+  const body = await c.req.json();
+  const sessionId = body.sessionId;
+  // UUID can come from query param (api.js sends it in URL) or body
+  const uuid = c.req.query("uuid") || body.uuid;
+
+  if (!sessionId || !uuid) {
+    return c.json({ error: "sessionId and uuid are required" }, 400);
+  }
+
+  const session = storeGetSession(sessionId);
+  if (!session) {
+    return c.json({ error: "Session not found" }, 404);
+  }
+
+  storeBindSession(sessionId, uuid);
+  return c.json({ ok: true, sessionId });
+});
+
+export default app;

packages/remote-control-server/src/routes/web/control.ts

@@ -0,0 +1,64 @@
+import { Hono } from "hono";
+import { uuidAuth } from "../../auth/middleware";
+import { getSession, updateSessionStatus } from "../../services/session";
+import { publishSessionEvent } from "../../services/transport";
+import { getEventBus } from "../../transport/event-bus";
+import { storeIsSessionOwner } from "../../store";
+
+const app = new Hono();
+
+function checkOwnership(c: { get: (key: string) => string | undefined }, sessionId: string) {
+  const uuid = c.get("uuid");
+  if (!storeIsSessionOwner(sessionId, uuid)) {
+    return { error: true, session: null };
+  }
+  const session = getSession(sessionId);
+  if (!session) {
+    return { error: true, session: null };
+  }
+  return { error: false, session };
+}
+
+/** POST /web/sessions/:id/events — Send user message to session */
+app.post("/sessions/:id/events", uuidAuth, async (c) => {
+  const sessionId = c.req.param("id")!;
+  const { error } = checkOwnership(c, sessionId);
+  if (error) {
+    return c.json({ error: { type: "forbidden", message: "Not your session" } }, 403);
+  }
+
+  const body = await c.req.json();
+  const eventType = body.type || "user";
+  console.log(`[RC-DEBUG] web -> server: POST /web/sessions/${sessionId}/events type=${eventType} content=${JSON.stringify(body).slice(0, 200)}`);
+  const event = publishSessionEvent(sessionId, eventType, body, "outbound");
+  console.log(`[RC-DEBUG] web -> server: published outbound event id=${event.id} type=${event.type} direction=${event.direction} subscribers=${getEventBus(sessionId).subscriberCount()}`);
+  return c.json({ status: "ok", event }, 200);
+});
+
+/** POST /web/sessions/:id/control — Send control request (permission approval etc) */
+app.post("/sessions/:id/control", uuidAuth, async (c) => {
+  const sessionId = c.req.param("id")!;
+  const { error } = checkOwnership(c, sessionId);
+  if (error) {
+    return c.json({ error: { type: "forbidden", message: "Not your session" } }, 403);
+  }
+
+  const body = await c.req.json();
+  const event = publishSessionEvent(sessionId, body.type || "control_request", body, "outbound");
+  return c.json({ status: "ok", event }, 200);
+});
+
+/** POST /web/sessions/:id/interrupt — Interrupt session */
+app.post("/sessions/:id/interrupt", uuidAuth, async (c) => {
+  const sessionId = c.req.param("id")!;
+  const { error } = checkOwnership(c, sessionId);
+  if (error) {
+    return c.json({ error: { type: "forbidden", message: "Not your session" } }, 403);
+  }
+
+  publishSessionEvent(sessionId, "interrupt", { action: "interrupt" }, "outbound");
+  updateSessionStatus(sessionId, "idle");
+  return c.json({ status: "ok" }, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/web/environments.ts

@@ -0,0 +1,14 @@
+import { Hono } from "hono";
+import { uuidAuth } from "../../auth/middleware";
+import { listActiveEnvironmentsResponse } from "../../services/environment";
+
+const app = new Hono();
+
+/** GET /web/environments — List active environments (UUID-based, no user filtering) */
+app.get("/environments", uuidAuth, async (c) => {
+  // Environments are shared across all UUIDs for now
+  const envs = listActiveEnvironmentsResponse();
+  return c.json(envs, 200);
+});
+
+export default app;

packages/remote-control-server/src/routes/web/sessions.ts

@@ -0,0 +1,100 @@
+import { Hono } from "hono";
+import { uuidAuth } from "../../auth/middleware";
+import { getSession, createSession } from "../../services/session";
+import { storeListSessionsByOwnerUuid, storeIsSessionOwner, storeBindSession } from "../../store";
+import { createWorkItem } from "../../services/work-dispatch";
+import { listSessionSummariesByOwnerUuid } from "../../services/session";
+import { createSSEStream } from "../../transport/sse-writer";
+import { getEventBus } from "../../transport/event-bus";
+
+const app = new Hono();
+
+/** POST /web/sessions — Create a session from web UI */
+app.post("/sessions", uuidAuth, async (c) => {
+  const uuid = c.get("uuid");
+  const body = await c.req.json();
+  const session = createSession({
+    environment_id: body.environment_id || null,
+    title: body.title || "New Session",
+    source: "web",
+    permission_mode: body.permission_mode || "default",
+  });
+
+  // Auto-bind to creator's UUID
+  storeBindSession(session.id, uuid);
+
+  // Dispatch work to environment if specified
+  if (body.environment_id) {
+    try {
+      await createWorkItem(body.environment_id, session.id);
+    } catch (err) {
+      console.error(`[RCS] Failed to create work item: ${(err as Error).message}`);
+    }
+  }
+
+  return c.json(session, 200);
+});
+
+/** GET /web/sessions — List sessions owned by the requesting UUID */
+app.get("/sessions", uuidAuth, async (c) => {
+  const uuid = c.get("uuid");
+  const sessions = storeListSessionsByOwnerUuid(uuid);
+  return c.json(sessions, 200);
+});
+
+/** GET /web/sessions/all — List sessions owned by the requesting UUID (unowned sessions excluded) */
+app.get("/sessions/all", uuidAuth, async (c) => {
+  const uuid = c.get("uuid");
+  const sessions = listSessionSummariesByOwnerUuid(uuid);
+  return c.json(sessions, 200);
+});
+
+/** GET /web/sessions/:id — Session detail */
+app.get("/sessions/:id", uuidAuth, async (c) => {
+  const uuid = c.get("uuid");
+  const sessionId = c.req.param("id")!;
+  if (!storeIsSessionOwner(sessionId, uuid)) {
+    return c.json({ error: { type: "forbidden", message: "Not your session" } }, 403);
+  }
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+  return c.json(session, 200);
+});
+
+/** GET /web/sessions/:id/history — Historical events for session */
+app.get("/sessions/:id/history", uuidAuth, async (c) => {
+  const uuid = c.get("uuid");
+  const sessionId = c.req.param("id")!;
+  if (!storeIsSessionOwner(sessionId, uuid)) {
+    return c.json({ error: { type: "forbidden", message: "Not your session" } }, 403);
+  }
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+
+  const bus = getEventBus(sessionId);
+  const events = bus.getEventsSince(0);
+  return c.json({ events }, 200);
+});
+
+/** SSE /web/sessions/:id/events — Real-time event stream */
+app.get("/sessions/:id/events", uuidAuth, async (c) => {
+  const uuid = c.get("uuid");
+  const sessionId = c.req.param("id")!;
+  if (!storeIsSessionOwner(sessionId, uuid)) {
+    return c.json({ error: { type: "forbidden", message: "Not your session" } }, 403);
+  }
+  const session = getSession(sessionId);
+  if (!session) {
+    return c.json({ error: { type: "not_found", message: "Session not found" } }, 404);
+  }
+
+  const lastEventId = c.req.header("Last-Event-ID");
+  const fromSeqNum = lastEventId ? parseInt(lastEventId) : 0;
+  return createSSEStream(c, sessionId, fromSeqNum);
+});
+
+export default app;

packages/remote-control-server/src/services/disconnect-monitor.ts

@@ -0,0 +1,32 @@
+import { storeListActiveEnvironments, storeUpdateEnvironment } from "../store";
+import { storeListSessions, storeUpdateSession } from "../store";
+import { config } from "../config";
+
+export function startDisconnectMonitor() {
+  const timeoutMs = config.disconnectTimeout * 1000;
+
+  setInterval(() => {
+    const now = Date.now();
+
+    // Check environment heartbeat timeout
+    const envs = storeListActiveEnvironments();
+    for (const env of envs) {
+      if (env.lastPollAt && now - env.lastPollAt.getTime() > timeoutMs) {
+        console.log(`[RCS] Environment ${env.id} timed out (no poll for ${Math.round((now - env.lastPollAt.getTime()) / 1000)}s)`);
+        storeUpdateEnvironment(env.id, { status: "disconnected" });
+      }
+    }
+
+    // Check session timeout (2x disconnect timeout with no update)
+    const sessions = storeListSessions();
+    for (const session of sessions) {
+      if (session.status === "running" || session.status === "idle") {
+        const elapsed = now - session.updatedAt.getTime();
+        if (elapsed > timeoutMs * 2) {
+          console.log(`[RCS] Session ${session.id} marked inactive (no update for ${Math.round(elapsed / 1000)}s)`);
+          storeUpdateSession(session.id, { status: "inactive" });
+        }
+      }
+    }
+  }, 60_000); // Check every minute
+}

packages/remote-control-server/src/services/environment.ts

@@ -0,0 +1,68 @@
+import { config } from "../config";
+import {
+  storeCreateEnvironment,
+  storeGetEnvironment,
+  storeUpdateEnvironment,
+  storeListActiveEnvironments,
+  storeListActiveEnvironmentsByUsername,
+} from "../store";
+import type { RegisterEnvironmentRequest, EnvironmentResponse } from "../types/api";
+import type { EnvironmentRecord } from "../store";
+
+function toResponse(row: EnvironmentRecord): EnvironmentResponse {
+  return {
+    id: row.id,
+    machine_name: row.machineName,
+    directory: row.directory,
+    branch: row.branch,
+    status: row.status,
+    username: row.username,
+    last_poll_at: row.lastPollAt ? row.lastPollAt.getTime() / 1000 : null,
+  };
+}
+
+export function registerEnvironment(req: RegisterEnvironmentRequest & { metadata?: { worker_type?: string }; username?: string }) {
+  const secret = config.apiKeys[0] || "";
+  const workerType = req.worker_type || req.metadata?.worker_type;
+  const record = storeCreateEnvironment({
+    secret,
+    machineName: req.machine_name,
+    directory: req.directory,
+    branch: req.branch,
+    gitRepoUrl: req.git_repo_url,
+    maxSessions: req.max_sessions,
+    workerType,
+    bridgeId: req.bridge_id,
+    username: req.username,
+  });
+
+  return { environment_id: record.id, environment_secret: record.secret, status: record.status as "active" };
+}
+
+export function deregisterEnvironment(envId: string) {
+  storeUpdateEnvironment(envId, { status: "deregistered" });
+}
+
+export function getEnvironment(envId: string) {
+  return storeGetEnvironment(envId);
+}
+
+export function updatePollTime(envId: string) {
+  storeUpdateEnvironment(envId, { lastPollAt: new Date() });
+}
+
+export function listActiveEnvironments() {
+  return storeListActiveEnvironments();
+}
+
+export function listActiveEnvironmentsResponse(): EnvironmentResponse[] {
+  return storeListActiveEnvironments().map(toResponse);
+}
+
+export function listActiveEnvironmentsByUsername(username: string): EnvironmentResponse[] {
+  return storeListActiveEnvironmentsByUsername(username).map(toResponse);
+}
+
+export function reconnectEnvironment(envId: string) {
+  storeUpdateEnvironment(envId, { status: "active" });
+}

packages/remote-control-server/src/services/session.ts

@@ -0,0 +1,103 @@
+import {
+  storeCreateSession,
+  storeGetSession,
+  storeUpdateSession,
+  storeListSessions,
+  storeListSessionsByUsername,
+  storeListSessionsByEnvironment,
+  storeListSessionsByOwnerUuid,
+} from "../store";
+import { removeEventBus } from "../transport/event-bus";
+import type { CreateSessionRequest, CreateCodeSessionRequest, SessionResponse, SessionSummaryResponse } from "../types/api";
+
+function toResponse(row: { id: string; environmentId: string | null; title: string | null; status: string; source: string; permissionMode: string | null; workerEpoch: number; username: string | null; createdAt: Date; updatedAt: Date }): SessionResponse {
+  return {
+    id: row.id,
+    environment_id: row.environmentId,
+    title: row.title,
+    status: row.status,
+    source: row.source,
+    permission_mode: row.permissionMode,
+    worker_epoch: row.workerEpoch,
+    username: row.username,
+    created_at: row.createdAt.getTime() / 1000,
+    updated_at: row.updatedAt.getTime() / 1000,
+  };
+}
+
+export function createSession(req: CreateSessionRequest & { username?: string }): SessionResponse {
+  const record = storeCreateSession({
+    environmentId: req.environment_id,
+    title: req.title,
+    source: req.source,
+    permissionMode: req.permission_mode,
+    username: req.username,
+  });
+  return toResponse(record);
+}
+
+export function createCodeSession(req: CreateCodeSessionRequest): SessionResponse {
+  const record = storeCreateSession({
+    idPrefix: "cse_",
+    title: req.title,
+    source: req.source,
+    permissionMode: req.permission_mode,
+  });
+  return toResponse(record);
+}
+
+export function getSession(sessionId: string): SessionResponse | null {
+  const record = storeGetSession(sessionId);
+  return record ? toResponse(record) : null;
+}
+
+export function updateSessionTitle(sessionId: string, title: string) {
+  storeUpdateSession(sessionId, { title });
+}
+
+export function updateSessionStatus(sessionId: string, status: string) {
+  storeUpdateSession(sessionId, { status });
+}
+
+export function archiveSession(sessionId: string) {
+  storeUpdateSession(sessionId, { status: "archived" });
+  removeEventBus(sessionId);
+}
+
+export function incrementEpoch(sessionId: string): number {
+  const record = storeGetSession(sessionId);
+  if (!record) throw new Error("Session not found");
+  const newEpoch = record.workerEpoch + 1;
+  storeUpdateSession(sessionId, { workerEpoch: newEpoch });
+  return newEpoch;
+}
+
+export function listSessions() {
+  return storeListSessions().map(toResponse);
+}
+
+function toSummaryResponse(row: { id: string; title: string | null; status: string; username: string | null; updatedAt: Date }): SessionSummaryResponse {
+  return {
+    id: row.id,
+    title: row.title,
+    status: row.status,
+    username: row.username,
+    updated_at: row.updatedAt.getTime() / 1000,
+  };
+}
+
+export function listSessionSummaries(): SessionSummaryResponse[] {
+  return storeListSessions().map(toSummaryResponse);
+}
+
+export function listSessionSummariesByOwnerUuid(uuid: string): SessionSummaryResponse[] {
+  return storeListSessionsByOwnerUuid(uuid).map(toSummaryResponse);
+}
+
+export function listSessionSummariesByUsername(username: string): SessionSummaryResponse[] {
+  return storeListSessionsByUsername(username).map(toSummaryResponse);
+}
+
+export function listSessionsByEnvironment(envId: string) {
+  return storeListSessionsByEnvironment(envId).map(toResponse);
+}

packages/remote-control-server/src/services/transport.ts

@@ -0,0 +1,93 @@
+import { getEventBus } from "../transport/event-bus";
+import { v4 as uuid } from "uuid";
+
+/**
+ * Extract plain text from various message payload formats.
+ * Handles:
+ *   { content: "text" }
+ *   { message: { role: "user", content: "text" } }
+ *   { message: { content: [{type:"text",text:"..."}] } }
+ */
+function extractContent(payload: unknown): string {
+  if (!payload || typeof payload !== "object") {
+    return typeof payload === "string" ? payload : "";
+  }
+
+  const p = payload as Record<string, unknown>;
+
+  // Direct content field
+  if (typeof p.content === "string" && p.content) return p.content;
+
+  // message.content (child process format)
+  const msg = p.message;
+  if (msg && typeof msg === "object") {
+    const mc = (msg as Record<string, unknown>).content;
+    if (typeof mc === "string") return mc;
+    if (Array.isArray(mc)) {
+      return mc
+        .filter((b: unknown) => typeof b === "object" && b !== null && (b as Record<string, unknown>).type === "text")
+        .map((b: Record<string, unknown>) => (b as Record<string, unknown>).text || "")
+        .join("");
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Normalize event payload into a flat structure with guaranteed `content` string.
+ * Preserves original payload in `raw` field and keeps tool-specific fields.
+ */
+export function normalizePayload(type: string, payload: unknown): Record<string, unknown> {
+  if (!payload || typeof payload !== "object") {
+    return { content: typeof payload === "string" ? payload : "", raw: payload };
+  }
+
+  const p = payload as Record<string, unknown>;
+  const content = extractContent(payload);
+
+  const normalized: Record<string, unknown> = {
+    content,
+    raw: payload,
+  };
+
+  // Preserve tool fields
+  if (p.tool_name) normalized.tool_name = p.tool_name;
+  if (p.name) normalized.tool_name = p.name;
+  if (p.tool_input) normalized.tool_input = p.tool_input;
+  if (p.input) normalized.tool_input = p.input;
+
+  // Preserve permission fields
+  if (p.request_id) normalized.request_id = p.request_id;
+  if (p.request) normalized.request = p.request;
+  if (p.approved !== undefined) normalized.approved = p.approved;
+  if (p.updated_input) normalized.updated_input = p.updated_input;
+
+  // Preserve message field for backward compat
+  if (p.message) normalized.message = p.message;
+
+  return normalized;
+}
+
+/** Publish an event to a session's bus (in-memory only) */
+export function publishSessionEvent(
+  sessionId: string,
+  type: string,
+  payload: unknown,
+  direction: "inbound" | "outbound",
+) {
+  const bus = getEventBus(sessionId);
+  const eventId = uuid();
+
+  const normalized = normalizePayload(type, payload);
+
+  const event = bus.publish({
+    id: eventId,
+    sessionId,
+    type,
+    payload: normalized,
+    direction,
+  });
+
+  return event;
+}

packages/remote-control-server/src/services/work-dispatch.ts

@@ -0,0 +1,98 @@
+import {
+  storeCreateWorkItem,
+  storeGetWorkItem,
+  storeGetPendingWorkItem,
+  storeUpdateWorkItem,
+  storeListSessionsByEnvironment,
+  storeGetEnvironment,
+} from "../store";
+import { config } from "../config";
+import { getBaseUrl } from "../config";
+import type { WorkResponse } from "../types/api";
+
+/** Encode work secret as base64 JSON (no JWT — just API key as token) */
+function encodeWorkSecret(): string {
+  const payload = {
+    version: 1,
+    session_ingress_token: config.apiKeys[0] || "",
+    api_base_url: getBaseUrl(),
+    sources: [] as string[],
+    auth: [] as string[],
+    use_code_sessions: false,
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+export async function createWorkItem(environmentId: string, sessionId: string): Promise<string> {
+  // Validate environment exists and is active
+  const env = storeGetEnvironment(environmentId);
+  if (!env) {
+    throw new Error(`Environment ${environmentId} not found`);
+  }
+  if (env.status !== "active") {
+    throw new Error(`Environment ${environmentId} is not active (status: ${env.status})`);
+  }
+
+  const secret = encodeWorkSecret();
+  const record = storeCreateWorkItem({ environmentId, sessionId, secret });
+  console.log(`[RCS] Work item created: ${record.id} for env=${environmentId} session=${sessionId}`);
+  return record.id;
+}
+
+/** Long-poll for work — blocks until work is available or timeout.
+ *  Returns null when no work is available, matching the CLI bridge client protocol. */
+export async function pollWork(environmentId: string, timeoutSeconds = config.pollTimeout): Promise<WorkResponse | null> {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+
+  while (Date.now() < deadline) {
+    const item = storeGetPendingWorkItem(environmentId);
+
+    if (item) {
+      storeUpdateWorkItem(item.id, { state: "dispatched" });
+
+      return {
+        id: item.id,
+        type: "work",
+        environment_id: environmentId,
+        state: "dispatched",
+        data: {
+          type: "session",
+          id: item.sessionId,
+        },
+        secret: item.secret,
+        created_at: item.createdAt.toISOString(),
+      };
+    }
+
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  return null;
+}
+
+export function ackWork(workId: string) {
+  storeUpdateWorkItem(workId, { state: "acked" });
+}
+
+export function stopWork(workId: string) {
+  storeUpdateWorkItem(workId, { state: "completed" });
+}
+
+export function heartbeatWork(workId: string): { lease_extended: boolean; state: string; last_heartbeat: string; ttl_seconds: number } {
+  storeUpdateWorkItem(workId, {} as any); // just bump updatedAt
+  const item = storeGetWorkItem(workId);
+  const now = new Date();
+  return {
+    lease_extended: true,
+    state: item?.state ?? "acked",
+    last_heartbeat: now.toISOString(),
+    ttl_seconds: config.heartbeatInterval * 2,
+  };
+}
+
+/** Reconnect: re-queue sessions associated with an environment */
+export function reconnectWorkForEnvironment(envId: string) {
+  const activeSessions = storeListSessionsByEnvironment(envId).filter((s) => s.status === "idle");
+  const promises = activeSessions.map((s) => createWorkItem(envId, s.id));
+  return Promise.all(promises);
+}

packages/remote-control-server/src/store.ts

@@ -0,0 +1,276 @@
+import { v4 as uuid } from "uuid";
+
+// ---------- Types ----------
+
+export interface UserRecord {
+  username: string;
+  createdAt: Date;
+}
+
+export interface EnvironmentRecord {
+  id: string;
+  secret: string;
+  machineName: string | null;
+  directory: string | null;
+  branch: string | null;
+  gitRepoUrl: string | null;
+  maxSessions: number;
+  workerType: string;
+  bridgeId: string | null;
+  status: string;
+  username: string | null;
+  lastPollAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface SessionRecord {
+  id: string;
+  environmentId: string | null;
+  title: string | null;
+  status: string;
+  source: string;
+  permissionMode: string | null;
+  workerEpoch: number;
+  username: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface WorkItemRecord {
+  id: string;
+  environmentId: string;
+  sessionId: string;
+  state: string;
+  secret: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// ---------- Stores (in-memory Maps) ----------
+
+const users = new Map<string, UserRecord>();
+const tokenToUser = new Map<string, { username: string; createdAt: Date }>();
+const environments = new Map<string, EnvironmentRecord>();
+const sessions = new Map<string, SessionRecord>();
+const workItems = new Map<string, WorkItemRecord>();
+
+// UUID → session ownership: sessionId → Set of UUIDs
+const sessionOwners = new Map<string, Set<string>>();
+
+// ---------- User ----------
+
+export function storeCreateUser(username: string): UserRecord {
+  const existing = users.get(username);
+  if (existing) return existing;
+  const record: UserRecord = { username, createdAt: new Date() };
+  users.set(username, record);
+  return record;
+}
+
+export function storeGetUser(username: string): UserRecord | undefined {
+  return users.get(username);
+}
+
+export function storeCreateToken(username: string, token: string): void {
+  tokenToUser.set(token, { username, createdAt: new Date() });
+}
+
+export function storeGetUserByToken(token: string): { username: string; createdAt: Date } | undefined {
+  return tokenToUser.get(token);
+}
+
+export function storeDeleteToken(token: string): boolean {
+  return tokenToUser.delete(token);
+}
+
+// ---------- Environment ----------
+
+export function storeCreateEnvironment(req: {
+  secret: string;
+  machineName?: string;
+  directory?: string;
+  branch?: string;
+  gitRepoUrl?: string;
+  maxSessions?: number;
+  workerType?: string;
+  bridgeId?: string;
+  username?: string;
+}): EnvironmentRecord {
+  const id = `env_${uuid().replace(/-/g, "")}`;
+  const now = new Date();
+  const record: EnvironmentRecord = {
+    id,
+    secret: req.secret,
+    machineName: req.machineName ?? null,
+    directory: req.directory ?? null,
+    branch: req.branch ?? null,
+    gitRepoUrl: req.gitRepoUrl ?? null,
+    maxSessions: req.maxSessions ?? 1,
+    workerType: req.workerType ?? "claude_code",
+    bridgeId: req.bridgeId ?? null,
+    status: "active",
+    username: req.username ?? null,
+    lastPollAt: now,
+    createdAt: now,
+    updatedAt: now,
+  };
+  environments.set(id, record);
+  return record;
+}
+
+export function storeGetEnvironment(id: string): EnvironmentRecord | undefined {
+  return environments.get(id);
+}
+
+export function storeUpdateEnvironment(id: string, patch: Partial<Pick<EnvironmentRecord, "status" | "lastPollAt" | "updatedAt">>): boolean {
+  const rec = environments.get(id);
+  if (!rec) return false;
+  Object.assign(rec, patch, { updatedAt: new Date() });
+  return true;
+}
+
+export function storeListActiveEnvironments(): EnvironmentRecord[] {
+  return [...environments.values()].filter((e) => e.status === "active");
+}
+
+export function storeListActiveEnvironmentsByUsername(username: string): EnvironmentRecord[] {
+  return [...environments.values()].filter((e) => e.status === "active" && e.username === username);
+}
+
+// ---------- Session ----------
+
+export function storeCreateSession(req: {
+  environmentId?: string | null;
+  title?: string | null;
+  source?: string;
+  permissionMode?: string | null;
+  idPrefix?: string;
+  username?: string | null;
+}): SessionRecord {
+  const id = `${req.idPrefix || "session_"}${uuid().replace(/-/g, "")}`;
+  const now = new Date();
+  const record: SessionRecord = {
+    id,
+    environmentId: req.environmentId ?? null,
+    title: req.title ?? null,
+    status: "idle",
+    source: req.source ?? "remote-control",
+    permissionMode: req.permissionMode ?? null,
+    workerEpoch: 0,
+    username: req.username ?? null,
+    createdAt: now,
+    updatedAt: now,
+  };
+  sessions.set(id, record);
+  return record;
+}
+
+export function storeGetSession(id: string): SessionRecord | undefined {
+  return sessions.get(id);
+}
+
+export function storeUpdateSession(id: string, patch: Partial<Pick<SessionRecord, "title" | "status" | "workerEpoch" | "updatedAt">>): boolean {
+  const rec = sessions.get(id);
+  if (!rec) return false;
+  Object.assign(rec, patch, { updatedAt: new Date() });
+  return true;
+}
+
+export function storeListSessions(): SessionRecord[] {
+  return [...sessions.values()];
+}
+
+export function storeListSessionsByUsername(username: string): SessionRecord[] {
+  return [...sessions.values()].filter((s) => s.username === username);
+}
+
+export function storeListSessionsByEnvironment(envId: string): SessionRecord[] {
+  return [...sessions.values()].filter((s) => s.environmentId === envId);
+}
+
+export function storeDeleteSession(id: string): boolean {
+  return sessions.delete(id);
+}
+
+// ---------- Work Items ----------
+
+// ---------- Session Ownership (UUID-based) ----------
+
+export function storeBindSession(sessionId: string, uuid: string): void {
+  let owners = sessionOwners.get(sessionId);
+  if (!owners) {
+    owners = new Set();
+    sessionOwners.set(sessionId, owners);
+  }
+  owners.add(uuid);
+}
+
+export function storeIsSessionOwner(sessionId: string, uuid: string): boolean {
+  const owners = sessionOwners.get(sessionId);
+  return owners ? owners.has(uuid) : false;
+}
+
+export function storeListSessionsByOwnerUuid(uuid: string): SessionRecord[] {
+  const result: SessionRecord[] = [];
+  for (const [sessionId, owners] of sessionOwners) {
+    if (owners.has(uuid)) {
+      const session = sessions.get(sessionId);
+      if (session) result.push(session);
+    }
+  }
+  return result;
+}
+
+// ---------- Work Items (cont.) ----------
+
+export function storeCreateWorkItem(req: {
+  environmentId: string;
+  sessionId: string;
+  secret: string;
+}): WorkItemRecord {
+  const id = `work_${uuid().replace(/-/g, "")}`;
+  const now = new Date();
+  const record: WorkItemRecord = {
+    id,
+    environmentId: req.environmentId,
+    sessionId: req.sessionId,
+    state: "pending",
+    secret: req.secret,
+    createdAt: now,
+    updatedAt: now,
+  };
+  workItems.set(id, record);
+  return record;
+}
+
+export function storeGetWorkItem(id: string): WorkItemRecord | undefined {
+  return workItems.get(id);
+}
+
+export function storeGetPendingWorkItem(environmentId: string): WorkItemRecord | undefined {
+  for (const item of workItems.values()) {
+    if (item.environmentId === environmentId && item.state === "pending") {
+      return item;
+    }
+  }
+  return undefined;
+}
+
+export function storeUpdateWorkItem(id: string, patch: Partial<Pick<WorkItemRecord, "state" | "updatedAt">>): boolean {
+  const rec = workItems.get(id);
+  if (!rec) return false;
+  Object.assign(rec, patch, { updatedAt: new Date() });
+  return true;
+}
+
+// ---------- Reset (for tests) ----------
+
+export function storeReset() {
+  users.clear();
+  tokenToUser.clear();
+  environments.clear();
+  sessions.clear();
+  workItems.clear();
+  sessionOwners.clear();
+}

packages/remote-control-server/src/transport/event-bus.ts

@@ -0,0 +1,85 @@
+export interface SessionEvent {
+  id: string;
+  sessionId: string;
+  type: string;
+  payload: unknown;
+  direction: "inbound" | "outbound";
+  seqNum: number;
+  createdAt: number;
+}
+
+type Subscriber = (event: SessionEvent) => void;
+
+export class EventBus {
+  private subscribers = new Set<Subscriber>();
+  private events: SessionEvent[] = [];
+  private seqNum = 0;
+  private closed = false;
+
+  subscribe(callback: Subscriber): () => void {
+    this.subscribers.add(callback);
+    return () => this.subscribers.delete(callback);
+  }
+
+  subscriberCount(): number {
+    return this.subscribers.size;
+  }
+
+  publish(event: Omit<SessionEvent, "seqNum" | "createdAt">): SessionEvent {
+    if (this.closed) throw new Error("EventBus is closed");
+    const full: SessionEvent = {
+      ...event,
+      seqNum: ++this.seqNum,
+      createdAt: Date.now(),
+    };
+    this.events.push(full);
+    console.log(`[RC-DEBUG] bus publish: sessionId=${event.sessionId} type=${event.type} dir=${event.direction} seq=${full.seqNum} subscribers=${this.subscribers.size}`);
+    for (const cb of this.subscribers) {
+      try {
+        cb(full);
+      } catch (err) {
+        console.error(`[RC-DEBUG] bus subscriber error:`, err);
+      }
+    }
+    return full;
+  }
+
+  getLastSeqNum(): number {
+    return this.seqNum;
+  }
+
+  getEventsSince(seqNum: number): SessionEvent[] {
+    const idx = this.events.findIndex((e) => e.seqNum > seqNum);
+    if (idx === -1) return [];
+    return this.events.slice(idx);
+  }
+
+  close() {
+    this.closed = true;
+    this.subscribers.clear();
+  }
+}
+
+/** Global registry of per-session event buses */
+const buses = new Map<string, EventBus>();
+
+export function getEventBus(sessionId: string): EventBus {
+  let bus = buses.get(sessionId);
+  if (!bus) {
+    bus = new EventBus();
+    buses.set(sessionId, bus);
+  }
+  return bus;
+}
+
+export function removeEventBus(sessionId: string) {
+  const bus = buses.get(sessionId);
+  if (bus) {
+    bus.close();
+    buses.delete(sessionId);
+  }
+}
+
+export function getAllEventBuses(): Map<string, EventBus> {
+  return buses;
+}

packages/remote-control-server/src/transport/sse-writer.ts

@@ -0,0 +1,117 @@
+import type { Context } from "hono";
+import type { SessionEvent } from "./event-bus";
+import { getEventBus } from "./event-bus";
+
+export interface SSEWriter {
+  send(event: SessionEvent): void;
+  close(): void;
+}
+
+export function createSSEWriter(c: Context): SSEWriter {
+  const stream = new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder();
+      c.req.raw.signal.addEventListener("abort", () => {
+        controller.close();
+      });
+
+      // Store encoder and controller for later use
+      (c as any)._sseEncoder = encoder;
+      (c as any)._sseController = controller;
+    },
+  });
+
+  return {
+    send(event: SessionEvent) {
+      const encoder = (c as any)._sseEncoder as TextEncoder;
+      const controller = (c as any)._sseController as ReadableStreamDefaultController;
+      if (!encoder || !controller) return;
+      const data = JSON.stringify({
+        type: event.type,
+        payload: event.payload,
+        direction: event.direction,
+        seqNum: event.seqNum,
+      });
+      const msg = `id: ${event.seqNum}\nevent: message\ndata: ${data}\n\n`;
+      controller.enqueue(encoder.encode(msg));
+    },
+    close() {
+      const controller = (c as any)._sseController as ReadableStreamDefaultController;
+      controller?.close();
+    },
+  };
+}
+
+/** Create SSE response stream for a session */
+export function createSSEStream(c: Context, sessionId: string, fromSeqNum = 0) {
+  const bus = getEventBus(sessionId);
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder();
+
+      // Send historical events if reconnecting
+      if (fromSeqNum > 0) {
+        const missed = bus.getEventsSince(fromSeqNum);
+        for (const event of missed) {
+          const data = JSON.stringify({
+            type: event.type,
+            payload: event.payload,
+            direction: event.direction,
+            seqNum: event.seqNum,
+          });
+          controller.enqueue(encoder.encode(`id: ${event.seqNum}\nevent: message\ndata: ${data}\n\n`));
+        }
+      }
+
+      // Send initial keepalive
+      controller.enqueue(encoder.encode(": keepalive\n\n"));
+
+      // Subscribe to new events
+      const unsub = bus.subscribe((event) => {
+        const data = JSON.stringify({
+          type: event.type,
+          payload: event.payload,
+          direction: event.direction,
+          seqNum: event.seqNum,
+        });
+        try {
+          console.log(`[RC-DEBUG] SSE -> web: sessionId=${sessionId} type=${event.type} dir=${event.direction} seq=${event.seqNum}`);
+          controller.enqueue(encoder.encode(`id: ${event.seqNum}\nevent: message\ndata: ${data}\n\n`));
+        } catch {
+          unsub();
+        }
+      });
+
+      // Keepalive interval
+      const keepalive = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": keepalive\n\n"));
+        } catch {
+          clearInterval(keepalive);
+          unsub();
+        }
+      }, 15000);
+
+      // Cleanup on abort
+      c.req.raw.signal.addEventListener("abort", () => {
+        unsub();
+        clearInterval(keepalive);
+        try {
+          controller.close();
+        } catch {
+          // already closed
+        }
+      });
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}

packages/remote-control-server/src/transport/ws-handler.ts

@@ -0,0 +1,273 @@
+import type { WSContext } from "hono/ws";
+import { getEventBus } from "./event-bus";
+import type { SessionEvent } from "./event-bus";
+import { publishSessionEvent } from "../services/transport";
+
+// Per-connection cleanup, keyed by sessionId (only one WS per session)
+interface CleanupEntry {
+  unsub: () => void;
+  keepalive: ReturnType<typeof setInterval>;
+  ws: WSContext;
+  openTime: number;
+}
+const cleanupBySession = new Map<string, CleanupEntry>();
+
+// Track all active WS connections for graceful shutdown
+const activeConnections = new Set<WSContext>();
+
+// Bridge sends keep_alive data frames every 120s. Send server-side keep_alive
+// every 60s to ensure the connection stays alive even without user messages.
+const SERVER_KEEPALIVE_INTERVAL_MS = 60_000;
+
+/**
+ * Convert internal EventBus event -> SDK message for bridge client.
+ */
+function toSDKMessage(event: SessionEvent): string {
+  const payload = event.payload as Record<string, unknown> | null;
+
+  let msg: Record<string, unknown>;
+
+  if (event.type === "user" || event.type === "user_message") {
+    msg = {
+      type: "user",
+      uuid: event.id,
+      session_id: event.sessionId,
+      message: {
+        role: "user",
+        content: payload?.content ?? payload?.message ?? "",
+      },
+    };
+  } else if (event.type === "permission_response" || event.type === "control_response") {
+    const approved = !!payload?.approved;
+    const existingResponse = payload?.response as Record<string, unknown> | undefined;
+    if (existingResponse) {
+      msg = { type: "control_response", response: existingResponse };
+    } else {
+      const updatedInput = payload?.updated_input as Record<string, unknown> | undefined;
+      const updatedPermissions = payload?.updated_permissions as Record<string, unknown>[] | undefined;
+      const feedbackMessage = payload?.message as string | undefined;
+      msg = {
+        type: "control_response",
+        response: {
+          subtype: approved ? "success" : "error",
+          request_id: payload?.request_id ?? "",
+          ...(approved
+            ? {
+                response: {
+                  behavior: "allow" as const,
+                  ...(updatedInput ? { updatedInput } : {}),
+                  ...(updatedPermissions ? { updatedPermissions } : {}),
+                },
+              }
+            : {
+                error: "Permission denied by user",
+                response: { behavior: "deny" as const },
+                ...(feedbackMessage ? { message: feedbackMessage } : {}),
+              }),
+        },
+      };
+    }
+  } else if (event.type === "interrupt") {
+    msg = {
+      type: "control_request",
+      request_id: event.id,
+      request: { subtype: "interrupt" },
+    };
+  } else if (event.type === "control_request") {
+    msg = {
+      type: "control_request",
+      request_id: payload?.request_id ?? event.id,
+      request: payload?.request ?? payload,
+    };
+  } else {
+    msg = {
+      type: event.type,
+      uuid: event.id,
+      session_id: event.sessionId,
+      message: payload,
+    };
+  }
+
+  // NDJSON format: each message MUST end with \n so the child process's
+  // line-based parser can split messages correctly.
+  return JSON.stringify(msg) + "\n";
+}
+
+/** Called from onOpen — subscribes to event bus, forwards outbound events to bridge WS */
+export function handleWebSocketOpen(ws: WSContext, sessionId: string) {
+  const openTime = Date.now();
+  console.log(`[RC-DEBUG] [WS] Open session=${sessionId}`);
+  activeConnections.add(ws);
+
+  // If there's an existing connection for this session, clean it up first
+  const existing = cleanupBySession.get(sessionId);
+  if (existing) {
+    console.log(`[WS] Replacing existing connection for session=${sessionId}`);
+    existing.unsub();
+    clearInterval(existing.keepalive);
+    activeConnections.delete(existing.ws);
+  }
+
+  const bus = getEventBus(sessionId);
+
+  // Replay ALL events (inbound + outbound) so the bridge can reconstruct
+  // the full conversation history — assistant replies are inbound events.
+  const missed = bus.getEventsSince(0);
+  if (missed.length > 0) {
+    console.log(`[WS] Replaying ${missed.length} missed event(s)`);
+    for (const event of missed) {
+      if (ws.readyState !== 1) break;
+      try {
+        ws.send(toSDKMessage(event));
+      } catch {
+        // ignore send errors during replay
+      }
+    }
+  }
+
+  const unsub = bus.subscribe((event: SessionEvent) => {
+    if (ws.readyState !== 1) return;
+    if (event.direction !== "outbound") return;
+    try {
+      const sdkMsg = toSDKMessage(event);
+      console.log(`[RC-DEBUG] [WS] -> bridge (outbound): type=${event.type} len=${sdkMsg.length} msg=${sdkMsg.slice(0, 300)}`);
+      ws.send(sdkMsg);
+    } catch (err) {
+      console.error("[RC-DEBUG] [WS] send error:", err);
+    }
+  });
+
+  const keepalive = setInterval(() => {
+    if (ws.readyState !== 1) {
+      clearInterval(keepalive);
+      return;
+    }
+    try {
+      ws.send('{"type":"keep_alive"}\n');
+    } catch {
+      clearInterval(keepalive);
+    }
+  }, SERVER_KEEPALIVE_INTERVAL_MS);
+
+  cleanupBySession.set(sessionId, { unsub, keepalive, ws, openTime });
+}
+
+/**
+ * Called from onMessage — bridge sends newline-delimited JSON.
+ */
+export function handleWebSocketMessage(ws: WSContext, sessionId: string, data: string) {
+  const lines = data.split("\n").filter((l) => l.trim());
+  for (const line of lines) {
+    try {
+      ingestBridgeMessage(sessionId, JSON.parse(line));
+    } catch (err) {
+      console.error("[WS] parse error:", err);
+    }
+  }
+}
+
+/** Called from onClose — unsubscribes from event bus */
+export function handleWebSocketClose(ws: WSContext, sessionId: string, code?: number, reason?: string) {
+  activeConnections.delete(ws);
+
+  const entry = cleanupBySession.get(sessionId);
+  const duration = entry ? Math.round((Date.now() - entry.openTime) / 1000) : -1;
+
+  console.log(`[WS] Close session=${sessionId} code=${code ?? "none"} reason=${reason || "(none)"} duration=${duration}s`);
+
+  if (entry) {
+    entry.unsub();
+    clearInterval(entry.keepalive);
+    cleanupBySession.delete(sessionId);
+  }
+}
+
+/**
+ * Derive event type from a child process message that may lack an explicit
+ * `type` field. The child's --print --output-format stream-json mode sends:
+ *   {"message":{"role":"user",...},"uuid":"..."}       → type "user"
+ *   {"message":{"role":"assistant",...},"uuid":"..."}  → type "assistant"
+ *   {"subtype":"success","uuid":"...","result":"..."}  → type "result"
+ */
+function deriveEventType(msg: Record<string, unknown>): string {
+  if (msg.type && typeof msg.type === "string") return msg.type;
+
+  // Child process stream-json format: message.role determines type
+  const message = msg.message as Record<string, unknown> | undefined;
+  if (message && typeof message.role === "string") {
+    return message.role; // "user", "assistant", "system"
+  }
+
+  // Result message
+  if (msg.subtype || msg.result !== undefined) return "result";
+
+  // System/init message
+  if (msg.session_id) return "system";
+
+  return "unknown";
+}
+
+/**
+ * Parse a single SDK message from bridge -> publish to EventBus as inbound.
+ */
+export function ingestBridgeMessage(sessionId: string, msg: Record<string, unknown>) {
+  if (msg.type === "keep_alive") return;
+
+  const eventType = deriveEventType(msg);
+
+  console.log(`[RC-DEBUG] [WS] <- bridge (inbound): sessionId=${sessionId} type=${eventType}${msg.uuid ? ` uuid=${msg.uuid}` : ""} msg=${JSON.stringify(msg).slice(0, 300)}`);
+
+  let payload: unknown;
+
+  if (eventType === "assistant" || eventType === "partial_assistant") {
+    const message = msg.message as Record<string, unknown> | undefined;
+    const content = message?.content;
+    // Extract text from content blocks for simple display
+    let text = "";
+    if (typeof content === "string") {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter((b: unknown) => b && typeof b === "object" && "type" in (b as Record<string, unknown>) && (b as Record<string, unknown>).type === "text")
+        .map((b: Record<string, unknown>) => (b as Record<string, unknown>).text || "")
+        .join("");
+    }
+    payload = { message: msg.message, uuid: msg.uuid, content: text };
+  } else if (eventType === "user" || eventType === "system") {
+    payload = { message: msg.message, uuid: msg.uuid };
+  } else if (eventType === "control_request") {
+    payload = { request_id: msg.request_id, request: msg.request };
+  } else if (eventType === "control_response") {
+    payload = { response: msg.response };
+  } else if (eventType === "result" || eventType === "result_success") {
+    payload = { subtype: msg.subtype, uuid: msg.uuid, result: msg.result };
+  } else {
+    payload = msg;
+  }
+
+  publishSessionEvent(sessionId, eventType, payload, "inbound");
+}
+
+/**
+ * Gracefully close all active WebSocket connections.
+ */
+export function closeAllConnections(): void {
+  const count = activeConnections.size;
+  if (count === 0) return;
+
+  console.log(`[WS] Gracefully closing ${count} active connection(s)...`);
+  for (const [sessionId, entry] of cleanupBySession) {
+    try {
+      entry.unsub();
+      clearInterval(entry.keepalive);
+      if (entry.ws.readyState === 1) {
+        entry.ws.close(1001, "server_shutdown");
+      }
+    } catch {
+      // ignore errors during shutdown
+    }
+  }
+  cleanupBySession.clear();
+  activeConnections.clear();
+  console.log("[WS] All connections closed");
+}

packages/remote-control-server/src/types/api.ts

@@ -0,0 +1,147 @@
+/** API 请求/响应类型定义 */
+
+// Hono context variable types
+declare module "hono" {
+  interface ContextVariableMap {
+    username?: string;
+    uuid?: string;
+    jwtPayload?: { session_id: string; role: string; iat: number; exp: number };
+  }
+}
+
+// --- Environment ---
+
+export interface RegisterEnvironmentRequest {
+  machine_name?: string;
+  directory?: string;
+  branch?: string;
+  git_repo_url?: string;
+  max_sessions?: number;
+  worker_type?: string;
+  bridge_id?: string;
+}
+
+export interface RegisterEnvironmentResponse {
+  id: string;
+  secret: string;
+  status: string;
+}
+
+export interface WorkResponse {
+  id: string;
+  type: "work";
+  environment_id: string;
+  state: string;
+  data: {
+    type: "session" | "healthcheck";
+    id: string;
+  };
+  secret: string;
+  created_at: string;
+}
+
+export interface WorkSecretPayload {
+  version: number;
+  session_ingress_token: string;
+  api_base_url: string;
+  sources: string[];
+  auth: string[];
+  use_code_sessions: boolean;
+}
+
+// --- Session ---
+
+export interface CreateSessionRequest {
+  environment_id?: string | null;
+  title?: string;
+  events?: unknown[];
+  source?: string;
+  permission_mode?: string;
+}
+
+export interface SessionResponse {
+  id: string;
+  environment_id: string | null;
+  title: string | null;
+  status: string;
+  source: string;
+  permission_mode: string | null;
+  worker_epoch: number;
+  username: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+// --- v2 Code Sessions ---
+
+export interface CreateCodeSessionRequest {
+  title?: string;
+  source?: string;
+  permission_mode?: string;
+}
+
+export interface BridgeResponse {
+  api_base_url: string;
+  worker_epoch: number;
+  worker_jwt: string;
+  expires_in: number;
+}
+
+// --- Web ---
+
+export interface EnvironmentResponse {
+  id: string;
+  machine_name: string | null;
+  directory: string | null;
+  branch: string | null;
+  status: string;
+  username: string | null;
+  last_poll_at: number | null;
+}
+
+export interface SessionSummaryResponse {
+  id: string;
+  title: string | null;
+  status: string;
+  username: string | null;
+  updated_at: number;
+}
+
+// --- Web Auth ---
+
+export interface WebLoginRequest {
+  apiKey: string;
+  username: string;
+}
+
+export interface WebLoginResponse {
+  token: string;
+  expires_in: number;
+}
+
+export interface WebControlRequest {
+  type: string;
+  content?: string;
+  [key: string]: unknown;
+}
+
+// --- Error ---
+
+export interface ErrorResponse {
+  error: {
+    type: string;
+    message: string;
+  };
+}
+
+// --- Event ---
+
+export interface SessionEventPayload {
+  id: string;
+  session_id: string;
+  type: string;
+  payload: unknown;
+  direction: "inbound" | "outbound";
+  seq_num: number;
+  created_at: number;
+}

packages/remote-control-server/src/types/messages.ts

@@ -0,0 +1,81 @@
+/** SDK 消息类型 — 与 CC CLI bridge 模块兼容 */
+export interface SDKMessage {
+  type: string;
+  content?: unknown;
+  [key: string]: unknown;
+}
+
+export interface UserMessage extends SDKMessage {
+  type: "user";
+  content: string;
+}
+
+export interface AssistantMessage extends SDKMessage {
+  type: "assistant";
+  content: string;
+}
+
+export interface PermissionRequest extends SDKMessage {
+  type: "permission_request";
+  tool_name: string;
+  tool_input: unknown;
+}
+
+export interface PermissionResponse extends SDKMessage {
+  type: "permission_response";
+  approved: boolean;
+  request_id: string;
+}
+
+export interface ControlRequest extends SDKMessage {
+  type: "control_request";
+  action: string;
+  [key: string]: unknown;
+}
+
+export type SessionEventType =
+  | "user"
+  | "assistant"
+  | "permission_request"
+  | "permission_response"
+  | "control_request"
+  | "tool_use"
+  | "tool_result"
+  | "status"
+  | "error";
+
+// --- Normalized Event Payloads (SSE contract) ---
+
+export interface NormalizedEventPayload {
+  content: string;
+  raw?: unknown;
+  [key: string]: unknown;
+}
+
+export interface UserEventPayload extends NormalizedEventPayload {
+  content: string;
+}
+
+export interface AssistantEventPayload extends NormalizedEventPayload {
+  content: string;
+}
+
+export interface ToolUseEventPayload extends NormalizedEventPayload {
+  content: string;
+  tool_name: string;
+  tool_input: unknown;
+}
+
+export interface ToolResultEventPayload extends NormalizedEventPayload {
+  content: string;
+}
+
+export interface PermissionEventPayload extends NormalizedEventPayload {
+  content: string;
+  request_id: string;
+  request: {
+    subtype: string;
+    tool_name: string;
+    tool_input: unknown;
+  };
+}

packages/remote-control-server/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "web"]
+}

packages/remote-control-server/web/api.js

@@ -0,0 +1,89 @@
+/**
+ * Remote Control — API Client (UUID-based auth)
+ */
+
+const BASE = ""; // same origin
+
+function generateUuid() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  // Fallback for non-secure contexts (HTTP without localhost)
+  return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (c) =>
+    (c ^ (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (c / 4)))).toString(16),
+  );
+}
+
+export function getUuid() {
+  let uuid = localStorage.getItem("rcs_uuid");
+  if (!uuid) {
+    uuid = generateUuid();
+    localStorage.setItem("rcs_uuid", uuid);
+  }
+  return uuid;
+}
+
+export function setUuid(uuid) {
+  localStorage.setItem("rcs_uuid", uuid);
+}
+
+async function api(method, path, body) {
+  const headers = { "Content-Type": "application/json" };
+  const uuid = getUuid();
+
+  // Append uuid as query param for auth
+  const sep = path.includes("?") ? "&" : "?";
+  const url = `${BASE}${path}${sep}uuid=${encodeURIComponent(uuid)}`;
+
+  const opts = { method, headers };
+  if (body !== undefined) opts.body = JSON.stringify(body);
+
+  const res = await fetch(url, opts);
+  const data = await res.json();
+
+  if (!res.ok) {
+    const err = data.error || { type: "unknown", message: res.statusText };
+    throw new Error(err.message || err.type);
+  }
+  return data;
+}
+
+export function apiBind(sessionId) {
+  return api("POST", "/web/bind", { sessionId });
+}
+
+export function apiFetchSessions() {
+  return api("GET", "/web/sessions");
+}
+
+export function apiFetchAllSessions() {
+  return api("GET", "/web/sessions/all");
+}
+
+export function apiFetchSession(id) {
+  return api("GET", `/web/sessions/${id}`);
+}
+
+export function apiFetchSessionHistory(id) {
+  return api("GET", `/web/sessions/${id}/history`);
+}
+
+export function apiFetchEnvironments() {
+  return api("GET", "/web/environments");
+}
+
+export function apiSendEvent(sessionId, body) {
+  return api("POST", `/web/sessions/${sessionId}/events`, body);
+}
+
+export function apiSendControl(sessionId, body) {
+  return api("POST", `/web/sessions/${sessionId}/control`, body);
+}
+
+export function apiInterrupt(sessionId) {
+  return api("POST", `/web/sessions/${sessionId}/interrupt`);
+}
+
+export function apiCreateSession(body) {
+  return api("POST", "/web/sessions", body);
+}

packages/remote-control-server/web/app.js

@@ -0,0 +1,618 @@
+/**
+ * Remote Control — Main App (Router + Orchestrator)
+ * UUID-based auth — no login required
+ */
+import { getUuid, setUuid, apiBind, apiFetchSessions, apiFetchAllSessions, apiFetchEnvironments, apiFetchSession, apiFetchSessionHistory, apiSendEvent, apiSendControl, apiInterrupt, apiCreateSession } from "./api.js";
+import { connectSSE, disconnectSSE } from "./sse.js";
+import { appendEvent, renderPermissionRequest, showLoading, isLoading, resetReplayState, renderReplayPendingRequests } from "./render.js";
+import { initTaskPanel, toggleTaskPanel, resetTaskState } from "./task-panel.js";
+import { esc, formatTime, statusClass } from "./utils.js";
+
+// ============================================================
+// State
+// ============================================================
+
+let currentSessionId = null;
+let dashboardInterval = null;
+let cachedEnvs = [];
+
+// ============================================================
+// Router
+// ============================================================
+
+function getPathSessionId() {
+  const match = window.location.pathname.match(/^\/code\/([^/]+)/);
+  return match ? match[1] : null;
+}
+
+function getUrlParam(name) {
+  return new URLSearchParams(window.location.search).get(name);
+}
+
+function showPage(name) {
+  const pages = ["dashboard", "session"];
+  for (const p of pages) {
+    const el = document.getElementById(`page-${p}`);
+    if (el) el.classList.toggle("hidden", p !== name);
+  }
+}
+
+function navigate(path) {
+  history.pushState(null, "", path);
+  handleRoute();
+}
+window.navigate = navigate;
+
+async function handleRoute() {
+  // Ensure we have a UUID
+  getUuid();
+
+  // Check for UUID import from QR scan (?uuid=xxx)
+  const importUuid = getUrlParam("uuid");
+  if (importUuid) {
+    setUuid(importUuid);
+    const url = new URL(window.location);
+    url.searchParams.delete("uuid");
+    history.replaceState(null, "", url);
+  }
+
+  // Check for CLI session bind (?sid=xxx)
+  const sid = getUrlParam("sid");
+  if (sid) {
+    try {
+      await apiBind(sid);
+      const url = new URL(window.location);
+      url.searchParams.delete("sid");
+      history.replaceState(null, "", `/code/${sid}`);
+      showPage("session");
+      stopDashboardRefresh();
+      renderSessionDetail(sid);
+      return;
+    } catch (err) {
+      console.error("Failed to bind session:", err);
+      alert("Session not found or bind failed: " + err.message);
+      history.replaceState(null, "", "/code/");
+    }
+  }
+
+  // Path-based routing: /code/session_xxx → session detail
+  const pathSessionId = getPathSessionId();
+  if (pathSessionId) {
+    try { await apiBind(pathSessionId); } catch { /* may already be bound */ }
+    showPage("session");
+    stopDashboardRefresh();
+    renderSessionDetail(pathSessionId);
+    return;
+  }
+
+  // Default: /code → dashboard
+  showPage("dashboard");
+  disconnectSSE();
+  renderDashboard();
+  startDashboardRefresh();
+}
+
+window.addEventListener("popstate", handleRoute);
+
+// ============================================================
+// Dashboard
+// ============================================================
+
+async function renderDashboard() {
+  try {
+    const [sessions, envs] = await Promise.all([apiFetchAllSessions(), apiFetchEnvironments()]);
+    cachedEnvs = envs || [];
+    renderEnvironmentList(cachedEnvs);
+    renderSessionList(sessions);
+  } catch (err) {
+    console.error("Dashboard render error:", err);
+  }
+}
+
+function renderEnvironmentList(envs) {
+  const container = document.getElementById("env-list");
+  if (!envs || envs.length === 0) {
+    container.innerHTML = '<div class="empty-state">No active environments</div>';
+    return;
+  }
+  container.innerHTML = envs.map((e) => `
+    <div class="env-card">
+      <div>
+        <div class="env-name">${esc(e.machine_name || e.id)}</div>
+        <div class="env-dir">${esc(e.directory || "")}</div>
+      </div>
+      <div style="text-align:right">
+        <span class="status-badge status-${statusClass(e.status)}">${esc(e.status)}</span>
+        <div class="env-branch">${e.branch ? esc(e.branch) : ""}</div>
+      </div>
+    </div>`).join("");
+}
+
+function renderSessionList(sessions) {
+  const container = document.getElementById("session-list");
+  if (!sessions || sessions.length === 0) {
+    container.innerHTML = '<div class="empty-state">No sessions</div>';
+    return;
+  }
+  sessions.sort((a, b) => (b.updated_at || 0) - (a.updated_at || 0));
+  container.innerHTML = sessions.map((s) => `
+    <div class="session-card" onclick="navigate('/code/${esc(s.id)}')">
+      <div>
+        <div class="session-title-text">${esc(s.title || s.id)}</div>
+        <div class="session-id-text">${esc(s.id)}</div>
+      </div>
+      <span class="status-badge status-${statusClass(s.status)}">${esc(s.status)}</span>
+      <span class="meta-item">${formatTime(s.created_at || s.updated_at)}</span>
+    </div>`).join("");
+}
+
+function startDashboardRefresh() {
+  stopDashboardRefresh();
+  dashboardInterval = setInterval(renderDashboard, 10000);
+}
+function stopDashboardRefresh() {
+  if (dashboardInterval) { clearInterval(dashboardInterval); dashboardInterval = null; }
+}
+
+// ============================================================
+// Session Detail
+// ============================================================
+
+async function renderSessionDetail(id) {
+  currentSessionId = id;
+
+  // Reset task state for new session and init panel
+  resetTaskState();
+  const taskPanelEl = document.getElementById("task-panel");
+  if (taskPanelEl) initTaskPanel(taskPanelEl);
+
+  try {
+    const session = await apiFetchSession(id);
+    document.getElementById("session-title").textContent = session.title || session.id;
+    document.getElementById("session-id").textContent = session.id;
+    document.getElementById("session-env").textContent = session.environment_id || "";
+    document.getElementById("session-time").textContent = formatTime(session.created_at);
+    const badge = document.getElementById("session-status");
+    badge.textContent = session.status;
+    badge.className = `status-badge status-${statusClass(session.status)}`;
+  } catch (err) {
+    alert("Failed to load session: " + err.message);
+    navigate("/code/");
+    return;
+  }
+  document.getElementById("event-stream").innerHTML = "";
+  document.getElementById("permission-area").innerHTML = "";
+  document.getElementById("permission-area").classList.add("hidden");
+
+  // Load historical events before connecting to live stream
+  resetReplayState();
+  let lastSeqNum = 0;
+  try {
+    const { events } = await apiFetchSessionHistory(id);
+    if (events && events.length > 0) {
+      for (const event of events) {
+        appendEvent(event, { replay: true });
+        if (event.seqNum && event.seqNum > lastSeqNum) lastSeqNum = event.seqNum;
+      }
+    }
+  } catch (err) {
+    console.warn("Failed to load session history:", err);
+  }
+  // Re-render any still-unresolved permission prompts from history
+  renderReplayPendingRequests();
+
+  connectSSE(id, appendEvent, lastSeqNum);
+}
+
+// ============================================================
+// Control Bar
+// ============================================================
+
+function setupControlBar() {
+  const input = document.getElementById("msg-input");
+  const actionBtn = document.getElementById("action-btn");
+  const iconSend = document.getElementById("action-icon-send");
+  const iconStop = document.getElementById("action-icon-stop");
+
+  function setBtnState(loading) {
+    actionBtn.classList.toggle("loading", loading);
+    actionBtn.setAttribute("aria-label", loading ? "Stop" : "Send");
+    iconSend.classList.toggle("hidden", loading);
+    iconStop.classList.toggle("hidden", !loading);
+  }
+
+  window.__updateActionBtn = setBtnState;
+
+  actionBtn.addEventListener("click", () => {
+    if (isLoading()) {
+      doInterrupt();
+    } else {
+      sendMessage();
+    }
+  });
+
+  input.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && !e.shiftKey && !e.isComposing) { e.preventDefault(); sendMessage(); }
+  });
+}
+
+async function doInterrupt() {
+  if (!currentSessionId) return;
+  const btn = document.getElementById("action-btn");
+  btn.disabled = true;
+  try {
+    await apiInterrupt(currentSessionId);
+    appendEvent({ type: "interrupt", payload: { message: "Session interrupted" } });
+  } catch (err) {
+    alert("Interrupt failed: " + err.message);
+  } finally {
+    btn.disabled = false;
+  }
+}
+
+async function sendMessage() {
+  const input = document.getElementById("msg-input");
+  const text = input.value.trim();
+  if (!text || !currentSessionId) return;
+  input.value = "";
+  try {
+    await apiSendEvent(currentSessionId, { type: "user", content: text });
+  } catch (err) {
+    alert("Failed to send: " + err.message);
+  }
+}
+
+// ============================================================
+// Permission Actions (exposed globally for onclick)
+// ============================================================
+
+window._approvePerm = async function (requestId, btn) {
+  btn.disabled = true;
+  try {
+    await apiSendControl(currentSessionId, { type: "permission_response", approved: true, request_id: requestId });
+    removePermissionPrompt(btn);
+    showLoading();
+  } catch (err) { alert("Failed to approve: " + err.message); btn.disabled = false; }
+};
+
+window._rejectPerm = async function (requestId, btn) {
+  btn.disabled = true;
+  try {
+    await apiSendControl(currentSessionId, { type: "permission_response", approved: false, request_id: requestId });
+    removePermissionPrompt(btn);
+  } catch (err) { alert("Failed to reject: " + err.message); btn.disabled = false; }
+};
+
+// ============================================================
+// AskUserQuestion interactions
+// ============================================================
+
+window._selectOption = function (btn, qIdx, oIdx, multiSelect) {
+  const panel = btn.closest(".ask-panel");
+  if (!panel) return;
+  if (!panel._answers) panel._answers = {};
+
+  if (multiSelect) {
+    // Toggle multi-select
+    btn.classList.toggle("selected");
+    if (!panel._answers[qIdx]) panel._answers[qIdx] = [];
+    const arr = panel._answers[qIdx];
+    const pos = arr.indexOf(oIdx);
+    if (pos >= 0) arr.splice(pos, 1);
+    else arr.push(oIdx);
+  } else {
+    // Single select — deselect siblings
+    const siblings = panel.querySelectorAll(`.ask-option[data-qidx="${qIdx}"]`);
+    siblings.forEach((s) => s.classList.remove("selected"));
+    btn.classList.add("selected");
+    panel._answers[qIdx] = oIdx;
+  }
+};
+
+window._submitOther = function (btn, qIdx) {
+  const row = btn.closest(".ask-other-row");
+  const input = row.querySelector(".ask-other-input");
+  const text = input.value.trim();
+  if (!text) return;
+  const panel = btn.closest(".ask-panel");
+  if (!panel) return;
+  if (!panel._answers) panel._answers = {};
+  panel._answers[qIdx] = text;
+  // Deselect any option buttons
+  panel.querySelectorAll(`.ask-option[data-qidx="${qIdx}"]`).forEach((s) => s.classList.remove("selected"));
+  input.value = "";
+  btn.textContent = "Sent!";
+  setTimeout(() => { btn.textContent = "Send"; }, 1000);
+};
+
+window._switchAskTab = function (btn, idx) {
+  const panel = btn.closest(".ask-panel");
+  if (!panel) return;
+  panel.querySelectorAll(".ask-tab").forEach((t) => t.classList.remove("active"));
+  panel.querySelectorAll(".ask-tab-page").forEach((p) => p.classList.remove("active"));
+  btn.classList.add("active");
+  const page = panel.querySelector(`.ask-tab-page[data-tab="${idx}"]`);
+  if (page) page.classList.add("active");
+  const total = panel.querySelectorAll(".ask-tab").length;
+  const prog = panel.querySelector(".ask-progress");
+  if (prog) prog.textContent = `${idx + 1} / ${total}`;
+};
+
+window._submitAnswers = async function (requestId, btn) {
+  btn.disabled = true;
+  const panel = btn.closest(".ask-panel");
+  const rawAnswers = panel?._answers || {};
+  const questions = panel?._questions || [];
+
+  // Build updatedInput: merge original input with user's answers
+  const answers = {};
+  for (const [qIdx, val] of Object.entries(rawAnswers)) {
+    const q = questions[parseInt(qIdx)];
+    if (!q) continue;
+    if (typeof val === "string") {
+      // "Other" free-text answer
+      answers[qIdx] = val;
+    } else if (typeof val === "number") {
+      // Selected option index — use label text
+      const opt = q.options?.[val];
+      answers[qIdx] = opt?.label || String(val);
+    } else if (Array.isArray(val)) {
+      // Multi-select — join labels
+      answers[qIdx] = val.map((i) => q.options?.[i]?.label || String(i));
+    }
+  }
+
+  try {
+    await apiSendControl(currentSessionId, {
+      type: "permission_response",
+      approved: true,
+      request_id: requestId,
+      updated_input: { questions, answers },
+    });
+    removePermissionPrompt(btn);
+    showLoading();
+  } catch (err) { alert("Failed to submit: " + err.message); btn.disabled = false; }
+};
+
+function removePermissionPrompt(btn) {
+  const prompt = btn.closest(".permission-prompt, .ask-panel, .plan-panel");
+  if (prompt) prompt.remove();
+  const area = document.getElementById("permission-area");
+  if (area && area.children.length === 0) area.classList.add("hidden");
+}
+
+// ============================================================
+// ExitPlanMode interactions
+// ============================================================
+
+window._selectPlanOption = function (btn, value) {
+  const panel = btn.closest(".plan-panel");
+  if (!panel) return;
+
+  // Deselect all siblings
+  panel.querySelectorAll(".plan-option").forEach((o) => o.classList.remove("selected"));
+  btn.classList.add("selected");
+  panel._selectedValue = value;
+
+  // Show/hide feedback textarea
+  const feedbackArea = panel.querySelector(".plan-feedback-area");
+  if (feedbackArea) {
+    feedbackArea.classList.toggle("visible", value === "no");
+  }
+};
+
+window._submitPlanResponse = async function (requestId, btn) {
+  const panel = btn.closest(".plan-panel");
+  if (!panel) return;
+
+  const selectedValue = panel._selectedValue;
+  if (!selectedValue) {
+    alert("Please select an option first.");
+    return;
+  }
+
+  btn.disabled = true;
+
+  try {
+    if (selectedValue === "no") {
+      // Rejection with optional feedback
+      const feedbackInput = panel.querySelector(".plan-feedback-input");
+      const feedback = feedbackInput ? feedbackInput.value.trim() : "";
+      await apiSendControl(currentSessionId, {
+        type: "permission_response",
+        approved: false,
+        request_id: requestId,
+        ...(feedback ? { message: feedback } : {}),
+      });
+      removePermissionPrompt(btn);
+    } else {
+      // Approval with permission mode
+      const modeMap = {
+        "yes-accept-edits": "acceptEdits",
+        "yes-default": "default",
+      };
+      const mode = modeMap[selectedValue] || "default";
+      const planContent = panel._planContent || "";
+
+      await apiSendControl(currentSessionId, {
+        type: "permission_response",
+        approved: true,
+        request_id: requestId,
+        ...(planContent ? { updated_input: { plan: planContent } } : {}),
+        updated_permissions: [
+          { type: "setMode", mode, destination: "session" },
+        ],
+      });
+      removePermissionPrompt(btn);
+      showLoading();
+    }
+  } catch (err) {
+    alert("Failed to submit: " + err.message);
+    btn.disabled = false;
+  }
+};
+
+// ============================================================
+// New Session Dialog
+// ============================================================
+
+function setupNewSessionDialog() {
+  const btn = document.getElementById("new-session-btn");
+  const dialog = document.getElementById("new-session-dialog");
+  const cancelBtn = document.getElementById("ns-cancel");
+  const createBtn = document.getElementById("ns-create");
+  const errorEl = document.getElementById("ns-error");
+  const titleInput = document.getElementById("ns-title");
+  const envSelect = document.getElementById("ns-env");
+
+  btn.addEventListener("click", () => {
+    envSelect.innerHTML = '<option value="">-- None --</option>';
+    for (const e of cachedEnvs) {
+      const opt = document.createElement("option");
+      opt.value = e.id;
+      opt.textContent = `${e.machine_name || e.id} (${e.branch || "no branch"})`;
+      envSelect.appendChild(opt);
+    }
+    errorEl.classList.add("hidden");
+    titleInput.value = "";
+    dialog.classList.remove("hidden");
+  });
+
+  cancelBtn.addEventListener("click", () => dialog.classList.add("hidden"));
+
+  createBtn.addEventListener("click", async () => {
+    createBtn.disabled = true;
+    errorEl.classList.add("hidden");
+    try {
+      const body = {};
+      if (titleInput.value.trim()) body.title = titleInput.value.trim();
+      if (envSelect.value) body.environment_id = envSelect.value;
+      const session = await apiCreateSession(body);
+      dialog.classList.add("hidden");
+      navigate(`/code/${session.id}`);
+    } catch (err) {
+      errorEl.textContent = err.message || "Failed to create session";
+      errorEl.classList.remove("hidden");
+    } finally {
+      createBtn.disabled = false;
+    }
+  });
+}
+
+// ============================================================
+// Identity Panel (QR code display + scan)
+// ============================================================
+
+function setupIdentityPanel() {
+  const btn = document.getElementById("nav-identity");
+  const panel = document.getElementById("identity-panel");
+  const closeBtn = panel.querySelector(".panel-close");
+  const uuidDisplay = document.getElementById("uuid-display");
+  const qrContainer = document.getElementById("qr-display");
+
+  // Show panel and generate QR code
+  btn.addEventListener("click", () => {
+    const uuid = getUuid();
+    uuidDisplay.textContent = uuid;
+    const qrUrl = `${window.location.origin}/code?uuid=${encodeURIComponent(uuid)}`;
+    qrContainer.innerHTML = "";
+    if (typeof QRCode !== "undefined") {
+      new QRCode(qrContainer, { text: qrUrl, width: 200, height: 200, correctLevel: QRCode.CorrectLevel.M });
+      // qrcodejs generates both canvas and img, hide the duplicate img
+      const img = qrContainer.querySelector("img");
+      if (img) img.remove()
+    }
+    panel.classList.remove("hidden");
+  });
+
+  closeBtn.addEventListener("click", () => panel.classList.add("hidden"));
+
+  // Click outside to close
+  panel.addEventListener("click", (e) => {
+    if (e.target === panel) panel.classList.add("hidden");
+  });
+
+  // Copy UUID to clipboard
+  document.getElementById("uuid-copy-btn").addEventListener("click", () => {
+    const uuid = getUuid();
+    navigator.clipboard.writeText(uuid).then(() => {
+      const btn = document.getElementById("uuid-copy-btn");
+      btn.textContent = "Copied!";
+      setTimeout(() => { btn.textContent = "Copy"; }, 2000);
+    });
+  });
+
+  // Scan QR from uploaded image
+  document.getElementById("qr-scan-btn").addEventListener("click", () => {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = "image/*";
+    input.onchange = (e) => {
+      const file = e.target.files[0];
+      if (!file) return;
+      const img = new Image();
+      img.onload = () => {
+        const canvas = document.createElement("canvas");
+        canvas.width = img.width;
+        canvas.height = img.height;
+        const ctx = canvas.getContext("2d");
+        ctx.drawImage(img, 0, 0);
+        const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+        if (typeof jsQR !== "undefined") {
+          const code = jsQR(imageData.data, imageData.width, imageData.height);
+          if (code && code.data) {
+            try {
+              const url = new URL(code.data);
+              const importedUuid = url.searchParams.get("uuid");
+              if (importedUuid) {
+                setUuid(importedUuid);
+                panel.classList.add("hidden");
+                navigate("/code/");
+                renderDashboard();
+                return;
+              }
+            } catch {
+              // Not a valid URL — try using raw data as UUID
+              if (code.data.length >= 32) {
+                setUuid(code.data);
+                panel.classList.add("hidden");
+                navigate("/code/");
+                renderDashboard();
+                return;
+              }
+            }
+            alert("No valid UUID found in QR code");
+          } else {
+            alert("No QR code found in image");
+          }
+        }
+      };
+      img.src = URL.createObjectURL(file);
+    };
+    input.click();
+  });
+}
+
+// ============================================================
+// Task Panel Toggle
+// ============================================================
+
+function setupTaskPanelToggle() {
+  window.__toggleTaskPanel = toggleTaskPanel;
+  const toggleBtn = document.getElementById("task-panel-toggle");
+  if (toggleBtn) {
+    toggleBtn.addEventListener("click", () => toggleTaskPanel());
+  }
+}
+
+// ============================================================
+// Init
+// ============================================================
+
+document.addEventListener("DOMContentLoaded", () => {
+  setupControlBar();
+  setupNewSessionDialog();
+  setupIdentityPanel();
+  setupTaskPanelToggle();
+  handleRoute();
+});

packages/remote-control-server/web/base.css

@@ -0,0 +1,116 @@
+/* === CSS Variables — Anthropic Design System === */
+:root {
+  /* Core palette — warm terracotta system */
+  --bg-primary: #FAF9F6;
+  --bg-card: #FFFFFF;
+  --bg-dark: #1A1612;
+  --bg-dark-hover: #2A2520;
+  --bg-dark-elevated: #332E28;
+  --bg-input: #F2EFEA;
+  --bg-input-focus: #FFFFFF;
+  --bg-user-msg: #D97757;
+  --bg-assistant-msg: #FFFFFF;
+  --bg-tool-card: #F5F3EF;
+  --bg-permission: #FFF9F0;
+  --text-primary: #1A1612;
+  --text-secondary: #6B6560;
+  --text-light: #FFFFFF;
+  --text-muted: #9B9590;
+  --text-inverse: #FAF9F6;
+  --border: #E8E4DF;
+  --border-light: #F0ECE7;
+  --border-focus: #D97757;
+  --accent: #D97757;
+  --accent-hover: #C4684A;
+  --accent-subtle: #FDF0EB;
+  --green: #3B8A6A;
+  --green-bg: #E8F5EE;
+  --yellow: #C49A2C;
+  --yellow-bg: #FFF8E8;
+  --orange: #D07A3A;
+  --orange-bg: #FFF3E8;
+  --red: #C44040;
+  --red-bg: #FDE8E8;
+  --blue: #4A7FC4;
+  --blue-bg: #E8F0FD;
+  --radius: 14px;
+  --radius-sm: 10px;
+  --radius-xs: 6px;
+  --shadow-sm: 0 1px 2px rgba(26, 22, 18, 0.04);
+  --shadow: 0 1px 3px rgba(26, 22, 18, 0.06), 0 2px 8px rgba(26, 22, 18, 0.04);
+  --shadow-md: 0 4px 16px rgba(26, 22, 18, 0.08), 0 1px 4px rgba(26, 22, 18, 0.04);
+  --shadow-lg: 0 8px 32px rgba(26, 22, 18, 0.10), 0 2px 8px rgba(26, 22, 18, 0.06);
+  --font-display: "Bricolage Grotesque", system-ui, -apple-system, sans-serif;
+  --font-sans: "Figtree", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-mono: "Fira Code", "SF Mono", Menlo, monospace;
+  --max-width: 880px;
+  --transition-fast: 0.15s cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-base: 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-slow: 0.4s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* === Reset === */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+html {
+  font-size: 15px;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  font-family: var(--font-sans);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  min-height: 100vh;
+  line-height: 1.6;
+  position: relative;
+}
+
+/* Subtle warm ambient light */
+body::before {
+  content: '';
+  position: fixed;
+  top: 0; left: 0;
+  width: 100%; height: 100%;
+  background:
+    radial-gradient(ellipse at 20% 50%, rgba(217, 119, 87, 0.03) 0%, transparent 50%),
+    radial-gradient(ellipse at 80% 20%, rgba(217, 119, 87, 0.02) 0%, transparent 50%),
+    radial-gradient(ellipse at 50% 80%, rgba(59, 138, 106, 0.02) 0%, transparent 50%);
+  pointer-events: none;
+  z-index: 0;
+}
+
+body > * { position: relative; z-index: 1; }
+
+a {
+  color: var(--accent);
+  text-decoration: none;
+  transition: color var(--transition-fast);
+}
+a:hover { color: var(--accent-hover); }
+
+button { cursor: pointer; font-family: inherit; }
+input, select, textarea { font-family: inherit; }
+
+.hidden { display: none !important; }
+
+/* === Selection === */
+::selection {
+  background: rgba(217, 119, 87, 0.2);
+  color: var(--text-primary);
+}
+
+/* === Focus Ring === */
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+/* === Scrollbar === */
+::-webkit-scrollbar { width: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 3px;
+}
+::-webkit-scrollbar-thumb:hover { background: var(--text-muted); }

packages/remote-control-server/web/components.css

@@ -0,0 +1,233 @@
+/* === Navbar — Anthropic === */
+nav {
+  background: var(--bg-card);
+  color: var(--text-primary);
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  border-bottom: 1px solid var(--border);
+  box-shadow: var(--shadow-sm);
+}
+
+.nav-inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0 32px;
+  height: 56px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.nav-logo {
+  color: var(--text-primary);
+  font-family: var(--font-display);
+  font-size: 1.05rem;
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  letter-spacing: -0.01em;
+  transition: opacity var(--transition-fast);
+}
+.nav-logo:hover { opacity: 0.7; text-decoration: none; }
+.nav-logo svg { flex-shrink: 0; }
+
+.nav-links { display: flex; align-items: center; gap: 8px; }
+
+.nav-link {
+  color: var(--text-secondary);
+  font-size: 0.88rem;
+  font-weight: 500;
+  background: none;
+  border: none;
+  padding: 6px 12px;
+  border-radius: var(--radius-xs);
+  transition: all var(--transition-fast);
+  letter-spacing: -0.005em;
+}
+.nav-link:hover {
+  color: var(--text-primary);
+  background: var(--bg-input);
+  text-decoration: none;
+}
+
+.btn-text { background: none; border: none; color: inherit; }
+
+/* === Buttons — Anthropic === */
+.btn-primary {
+  background: var(--accent);
+  color: var(--text-light);
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 11px 22px;
+  font-size: 0.92rem;
+  font-weight: 600;
+  letter-spacing: -0.005em;
+  transition: all var(--transition-fast);
+  box-shadow: 0 1px 2px rgba(217, 119, 87, 0.2);
+}
+.btn-primary:hover {
+  background: var(--accent-hover);
+  box-shadow: 0 2px 8px rgba(217, 119, 87, 0.3);
+  transform: translateY(-1px);
+}
+.btn-primary:active { transform: translateY(0); box-shadow: none; }
+.btn-primary:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
+}
+
+.btn-danger {
+  background: var(--red);
+  color: var(--text-light);
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 11px 18px;
+  font-size: 0.85rem;
+  font-weight: 600;
+  transition: all var(--transition-fast);
+}
+.btn-danger:hover { background: #B33838; transform: translateY(-1px); }
+.btn-danger:active { transform: translateY(0); }
+
+.btn-sm { padding: 8px 16px; font-size: 0.85rem; }
+
+.btn-outline {
+  background: transparent;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 8px 16px;
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text-primary);
+  transition: all var(--transition-fast);
+}
+.btn-outline:hover {
+  background: var(--bg-input);
+  border-color: var(--text-muted);
+}
+
+.btn-approve {
+  background: var(--green);
+  color: var(--text-light);
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 9px 20px;
+  font-size: 0.85rem;
+  font-weight: 600;
+  transition: all var(--transition-fast);
+}
+.btn-approve:hover { background: #347A5E; transform: translateY(-1px); }
+.btn-approve:active { transform: translateY(0); }
+
+.btn-reject {
+  background: transparent;
+  color: var(--red);
+  border: 1.5px solid var(--red);
+  border-radius: var(--radius-sm);
+  padding: 9px 20px;
+  font-size: 0.85rem;
+  font-weight: 600;
+  transition: all var(--transition-fast);
+}
+.btn-reject:hover { background: var(--red-bg); transform: translateY(-1px); }
+.btn-reject:active { transform: translateY(0); }
+
+/* === Status Badge — Anthropic === */
+.status-badge {
+  display: inline-flex;
+  align-items: center;
+  font-size: 0.72rem;
+  font-weight: 600;
+  padding: 3px 10px;
+  border-radius: 20px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.status-active, .status-running { background: var(--green-bg); color: var(--green); }
+.status-idle { background: var(--yellow-bg); color: var(--yellow); }
+.status-requires_action { background: var(--orange-bg); color: var(--orange); }
+.status-archived { background: #F0ECE7; color: var(--text-secondary); }
+.status-error { background: var(--red-bg); color: var(--red); }
+.status-default { background: #F0ECE7; color: var(--text-muted); }
+
+/* === Dialog — Anthropic === */
+.dialog-overlay {
+  position: fixed;
+  top: 0; left: 0;
+  width: 100%; height: 100%;
+  background: rgba(26, 22, 18, 0.3);
+  backdrop-filter: blur(4px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 200;
+  animation: fadeIn var(--transition-fast) ease-out;
+}
+
+.dialog-card {
+  background: var(--bg-card);
+  border-radius: 16px;
+  box-shadow: var(--shadow-lg);
+  padding: 32px;
+  width: 100%;
+  max-width: 440px;
+  border: 1px solid var(--border-light);
+  animation: slideUp var(--transition-base) ease-out;
+}
+.dialog-card h3 {
+  font-family: var(--font-display);
+  font-size: 1.15rem;
+  font-weight: 600;
+  margin-bottom: 20px;
+  letter-spacing: -0.01em;
+}
+.dialog-card label {
+  display: block;
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  margin-bottom: 6px;
+  margin-top: 16px;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+.dialog-card input,
+.dialog-card select {
+  width: 100%;
+  padding: 10px 14px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-input);
+  font-size: 0.92rem;
+  color: var(--text-primary);
+  outline: none;
+  transition: all var(--transition-fast);
+}
+.dialog-card input:focus,
+.dialog-card select:focus {
+  border-color: var(--accent);
+  background: var(--bg-input-focus);
+  box-shadow: 0 0 0 3px rgba(217, 119, 87, 0.12);
+}
+.dialog-actions {
+  display: flex;
+  gap: 10px;
+  justify-content: flex-end;
+  margin-top: 24px;
+}
+
+/* === Animations === */
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes slideUp {
+  from { opacity: 0; transform: translateY(8px) scale(0.98); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}

packages/remote-control-server/web/index.html

@@ -0,0 +1,151 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Remote Control — Claude Code</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,400;12..96,500;12..96,600;12..96,700&family=Figtree:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap" />
+  <link rel="stylesheet" href="./style.css" />
+</head>
+<body>
+  <!-- Nav Bar -->
+  <nav id="navbar">
+    <div class="nav-inner">
+      <a href="/code/" class="nav-logo">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+          <path d="M10 1L12.2 7.8L19 10L12.2 12.2L10 19L7.8 12.2L1 10L7.8 7.8L10 1Z" fill="#D97757"/>
+        </svg>
+        Remote Control
+      </a>
+      <div class="nav-links">
+        <a href="/code/" class="nav-link" id="nav-dashboard">Dashboard</a>
+        <button id="nav-identity" class="nav-link btn-text" title="Identity & QR">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" style="vertical-align:-2px;margin-right:4px;">
+            <path d="M6 8C7.66 8 9 6.66 9 5C9 3.34 7.66 2 6 2C4.34 2 3 3.34 3 5C3 6.66 4.34 8 6 8ZM6 10C3.99 10 0 11.01 0 13V14H12V13C12 11.01 8.01 10 6 10ZM13 8V5H11V8H8V10H11V13H13V10H16V8H13Z" fill="currentColor"/>
+          </svg>
+          Identity
+        </button>
+      </div>
+    </div>
+  </nav>
+
+  <!-- Dashboard Page -->
+  <section id="page-dashboard" class="page hidden">
+    <div class="dashboard-container">
+      <!-- Environments -->
+      <div class="dashboard-section">
+        <h2 class="section-title">Environments</h2>
+        <div id="env-list" class="card-list">
+          <div class="empty-state">No active environments</div>
+        </div>
+      </div>
+      <!-- Sessions -->
+      <div class="dashboard-section">
+        <div class="section-header">
+          <h2 class="section-title">Sessions</h2>
+          <button id="new-session-btn" class="btn-primary btn-sm">+ New Session</button>
+        </div>
+        <div id="session-list" class="card-list">
+          <div class="empty-state">No sessions</div>
+        </div>
+      </div>
+
+      <!-- New Session Dialog -->
+      <div id="new-session-dialog" class="dialog-overlay hidden">
+        <div class="dialog-card">
+          <h3>New Session</h3>
+          <label for="ns-title">Title (optional)</label>
+          <input type="text" id="ns-title" placeholder="My session" />
+          <label for="ns-env">Environment</label>
+          <select id="ns-env"></select>
+          <div id="ns-error" class="error-msg hidden"></div>
+          <div class="dialog-actions">
+            <button id="ns-cancel" class="btn-outline">Cancel</button>
+            <button id="ns-create" class="btn-primary">Create</button>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- Session Detail Page -->
+  <section id="page-session" class="page hidden">
+    <div class="session-container">
+      <!-- Header -->
+      <div class="session-header">
+        <a href="/code/" class="back-link">&larr; Dashboard</a>
+        <div class="session-meta">
+          <h2 id="session-title" class="session-detail-title">Session</h2>
+          <div class="session-meta-row">
+            <span id="session-id" class="meta-item"></span>
+            <span id="session-status" class="status-badge"></span>
+            <span id="session-env" class="meta-item"></span>
+            <span id="session-time" class="meta-item"></span>
+            <button id="task-panel-toggle" class="nav-link btn-text" title="Tasks & Todos">
+              Tasks <span id="task-badge" class="task-count-badge hidden">0</span>
+            </button>
+          </div>
+        </div>
+      </div>
+      <!-- Event Stream -->
+      <div id="event-stream" class="event-stream"></div>
+      <!-- Permission Prompt Area -->
+      <div id="permission-area" class="hidden"></div>
+      <!-- Control Bar -->
+      <div class="control-bar">
+        <input type="text" id="msg-input" placeholder="Type a message..." autocomplete="off" />
+        <button id="action-btn" class="action-btn" aria-label="Send">
+          <svg id="action-icon-send" width="20" height="20" viewBox="0 0 20 20" fill="none">
+            <path d="M3 10L17 3L10 17L9 11L3 10Z" fill="currentColor"/>
+          </svg>
+          <svg id="action-icon-stop" class="hidden" width="18" height="18" viewBox="0 0 18 18" fill="none">
+            <rect x="3" y="3" width="12" height="12" rx="2" fill="currentColor"/>
+          </svg>
+        </button>
+      </div>
+    </div>
+  </section>
+
+  <!-- Task Panel -->
+  <div id="task-panel" class="task-panel hidden"></div>
+
+  <!-- Identity Panel (QR display + scan) -->
+  <div id="identity-panel" class="identity-panel hidden">
+    <div class="identity-panel-inner">
+      <div class="identity-panel-header">
+        <h3>Identity</h3>
+        <button class="panel-close">&times;</button>
+      </div>
+      <div class="identity-panel-body">
+        <div class="identity-section">
+          <label>Your UUID</label>
+          <div class="uuid-row">
+            <code id="uuid-display" class="uuid-text"></code>
+            <button id="uuid-copy-btn" class="btn-outline btn-sm">Copy</button>
+          </div>
+        </div>
+        <div class="identity-section">
+          <label>Scan on another device</label>
+          <div id="qr-display" class="qr-container"></div>
+        </div>
+        <div class="identity-section">
+          <label>Import identity from QR</label>
+          <button id="qr-scan-btn" class="btn-outline">
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" style="vertical-align:-2px;margin-right:4px;">
+              <path d="M1 1H5V3H3V5H1V1ZM11 1H15V5H13V3H11V1ZM1 11H3V13H5V15H1V11ZM13 11H15V15H11V13H13V11ZM6 6H10V10H6V6Z" fill="currentColor"/>
+            </svg>
+            Upload QR Image
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- QR Libraries -->
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/jsqr@1.4.0/dist/jsQR.js"></script>
+  <script type="module" src="./app.js"></script>
+</body>
+</html>

packages/remote-control-server/web/messages.css

@@ -0,0 +1,481 @@
+/* === Event Stream === */
+.event-stream {
+  flex: 1;
+  overflow-y: auto;
+  padding: 20px 0;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  scroll-behavior: smooth;
+}
+
+/* === Message Bubbles — Anthropic / Claude === */
+.msg-row {
+  display: flex;
+  max-width: 82%;
+  animation: msgIn 0.3s ease-out;
+}
+
+@keyframes msgIn {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.msg-row.user { align-self: flex-end; }
+.msg-row.assistant { align-self: flex-start; }
+.msg-row.tool { align-self: flex-start; max-width: 95%; }
+.msg-row.system { align-self: center; }
+.msg-row.result { align-self: center; }
+
+.msg-bubble {
+  padding: 12px 18px;
+  border-radius: 18px;
+  font-size: 0.92rem;
+  line-height: 1.6;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+.msg-row.user .msg-bubble {
+  background: var(--accent);
+  color: var(--text-light);
+  border-bottom-right-radius: 6px;
+  box-shadow: 0 2px 8px rgba(217, 119, 87, 0.2);
+}
+
+.msg-row.assistant .msg-bubble {
+  background: var(--bg-card);
+  color: var(--text-primary);
+  border: 1px solid var(--border-light);
+  border-bottom-left-radius: 6px;
+  box-shadow: var(--shadow-sm);
+}
+
+.msg-row.system .msg-bubble {
+  background: transparent;
+  color: var(--text-muted);
+  font-size: 0.82rem;
+  text-align: center;
+  padding: 4px 12px;
+}
+
+.msg-row.result .msg-bubble {
+  background: var(--green-bg);
+  color: var(--green);
+  font-size: 0.85rem;
+  text-align: center;
+  padding: 6px 16px;
+  border-radius: 18px;
+  font-weight: 500;
+}
+
+/* === Tool Cards — Anthropic === */
+.tool-card {
+  background: var(--bg-tool-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 12px 16px;
+  width: 100%;
+  transition: border-color var(--transition-fast);
+}
+.tool-card:hover { border-color: var(--accent); }
+
+.tool-card-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 0.82rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  cursor: pointer;
+  user-select: none;
+  letter-spacing: -0.005em;
+}
+.tool-card-header:hover { color: var(--text-primary); }
+
+.tool-card-header .tool-icon {
+  color: var(--accent);
+  font-size: 0.7rem;
+  transition: transform var(--transition-fast);
+}
+.tool-card-header:hover .tool-icon { transform: rotate(90deg); }
+
+.tool-card-body {
+  margin-top: 10px;
+  font-family: var(--font-mono);
+  font-size: 0.78rem;
+  color: var(--text-secondary);
+  background: var(--bg-card);
+  border-radius: var(--radius-xs);
+  padding: 12px 14px;
+  white-space: pre-wrap;
+  word-break: break-all;
+  max-height: 240px;
+  overflow-y: auto;
+  border: 1px solid var(--border-light);
+}
+.tool-card-body.collapsed { display: none; }
+
+/* === Permission Prompt — Anthropic === */
+.permission-prompt {
+  background: var(--bg-permission);
+  border: 1px solid #F0D9A8;
+  border-radius: var(--radius);
+  padding: 20px 24px;
+  margin-top: 8px;
+  max-width: 95%;
+  align-self: flex-start;
+  box-shadow: var(--shadow);
+}
+.permission-prompt .perm-title {
+  font-family: var(--font-display);
+  font-weight: 600;
+  font-size: 0.92rem;
+  margin-bottom: 10px;
+  color: var(--orange);
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.permission-prompt .perm-tool {
+  font-family: var(--font-mono);
+  font-size: 0.82rem;
+  background: var(--bg-card);
+  padding: 10px 14px;
+  border-radius: var(--radius-xs);
+  margin-bottom: 14px;
+  white-space: pre-wrap;
+  word-break: break-all;
+  max-height: 160px;
+  overflow-y: auto;
+  border: 1px solid var(--border-light);
+}
+.permission-prompt .perm-actions { display: flex; gap: 10px; }
+.permission-prompt .perm-desc {
+  font-size: 0.88rem;
+  color: var(--text-secondary);
+  margin-bottom: 10px;
+  line-height: 1.5;
+}
+.permission-prompt .perm-tool-name {
+  font-size: 0.82rem;
+  color: var(--text-primary);
+  margin-bottom: 6px;
+}
+
+/* === AskUserQuestion Panel === */
+.ask-panel {
+  background: var(--bg-card);
+  border: 1.5px solid var(--accent);
+  border-radius: var(--radius);
+  padding: 20px 24px;
+  margin-top: 8px;
+  max-width: 95%;
+  align-self: flex-start;
+  box-shadow: 0 2px 12px rgba(217, 119, 87, 0.15);
+}
+.ask-panel .ask-title {
+  font-family: var(--font-display);
+  font-weight: 600;
+  font-size: 1rem;
+  margin-bottom: 16px;
+  color: var(--text-primary);
+}
+.ask-question {
+  margin-bottom: 18px;
+  padding-bottom: 14px;
+  border-bottom: 1px solid var(--border-light);
+}
+.ask-question:last-of-type { border-bottom: none; margin-bottom: 12px; }
+.ask-question-text {
+  font-size: 0.92rem;
+  font-weight: 500;
+  color: var(--text-primary);
+  margin-bottom: 8px;
+  line-height: 1.5;
+}
+.ask-header {
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 8px;
+}
+.ask-options { display: flex; flex-direction: column; gap: 6px; }
+.ask-option {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  padding: 10px 14px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  text-align: left;
+  font-size: 0.88rem;
+  color: var(--text-primary);
+}
+.ask-option:hover {
+  border-color: var(--accent);
+  background: rgba(217, 119, 87, 0.04);
+}
+.ask-option.selected {
+  border-color: var(--accent);
+  background: rgba(217, 119, 87, 0.1);
+  box-shadow: 0 0 0 1px var(--accent);
+}
+.ask-option-label { font-weight: 500; }
+.ask-option-desc {
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+  margin-top: 2px;
+}
+.ask-other-row {
+  display: flex;
+  gap: 6px;
+  margin-top: 6px;
+}
+.ask-other-input {
+  flex: 1;
+  padding: 8px 12px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  font-size: 0.85rem;
+  color: var(--text-primary);
+  outline: none;
+  transition: border-color var(--transition-fast);
+}
+.ask-other-input:focus { border-color: var(--accent); }
+.ask-other-btn {
+  padding: 8px 14px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  font-size: 0.85rem;
+  cursor: pointer;
+  color: var(--text-primary);
+  transition: all var(--transition-fast);
+}
+.ask-other-btn:hover { border-color: var(--accent); }
+.ask-actions { display: flex; gap: 10px; margin-top: 8px; }
+.ask-tabs {
+  display: flex;
+  gap: 0;
+  border-bottom: 1.5px solid var(--border);
+  margin-bottom: 14px;
+}
+.ask-tab {
+  padding: 8px 16px;
+  border: none;
+  background: none;
+  cursor: pointer;
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text-secondary);
+  border-bottom: 2px solid transparent;
+  margin-bottom: -1.5px;
+  transition: all var(--transition-fast);
+}
+.ask-tab:hover { color: var(--text-primary); }
+.ask-tab.active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+}
+.ask-tab-page { display: none; }
+.ask-tab-page.active { display: block; }
+.ask-tab-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: 16px;
+  padding-top: 12px;
+  border-top: 1px solid var(--border-light);
+}
+.ask-progress {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+  font-family: var(--font-mono);
+}
+
+/* === ExitPlanMode Panel === */
+.plan-panel {
+  background: var(--bg-card);
+  border: 1.5px solid #7C6FA0;
+  border-radius: var(--radius);
+  padding: 20px 24px;
+  margin-top: 8px;
+  max-width: 95%;
+  align-self: flex-start;
+  box-shadow: 0 2px 12px rgba(124, 111, 160, 0.18);
+}
+.plan-panel .plan-title {
+  font-family: var(--font-display);
+  font-weight: 600;
+  font-size: 1rem;
+  margin-bottom: 12px;
+  color: #7C6FA0;
+}
+.plan-panel .plan-content {
+  border: 1px dashed var(--border);
+  border-radius: var(--radius-sm);
+  padding: 14px 16px;
+  margin-bottom: 16px;
+  max-height: 320px;
+  overflow-y: auto;
+  font-size: 0.88rem;
+  line-height: 1.6;
+  color: var(--text-primary);
+}
+.plan-panel .plan-content pre {
+  background: var(--bg-tool-card);
+  padding: 10px;
+  border-radius: 6px;
+  overflow-x: auto;
+  margin: 6px 0;
+  font-family: var(--font-mono);
+  font-size: 0.82rem;
+}
+.plan-panel .plan-content code {
+  background: var(--bg-tool-card);
+  padding: 2px 5px;
+  border-radius: 3px;
+  font-family: var(--font-mono);
+  font-size: 0.85em;
+}
+.plan-panel .plan-content strong { font-weight: 600; }
+.plan-options { display: flex; flex-direction: column; gap: 6px; }
+.plan-option {
+  display: flex;
+  align-items: center;
+  padding: 10px 14px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  text-align: left;
+  font-size: 0.88rem;
+  color: var(--text-primary);
+  gap: 10px;
+}
+.plan-option:hover {
+  border-color: #7C6FA0;
+  background: rgba(124, 111, 160, 0.04);
+}
+.plan-option.selected {
+  border-color: #7C6FA0;
+  background: rgba(124, 111, 160, 0.1);
+  box-shadow: 0 0 0 1px #7C6FA0;
+}
+.plan-option-label { font-weight: 500; }
+.plan-option-desc {
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+  margin-top: 2px;
+}
+.plan-feedback-area {
+  margin-top: 10px;
+  display: none;
+}
+.plan-feedback-area.visible { display: block; }
+.plan-feedback-input {
+  width: 100%;
+  min-height: 60px;
+  padding: 10px 14px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  font-size: 0.85rem;
+  color: var(--text-primary);
+  outline: none;
+  resize: vertical;
+  font-family: inherit;
+  transition: border-color var(--transition-fast);
+}
+.plan-feedback-input:focus { border-color: #7C6FA0; }
+.plan-actions { display: flex; gap: 10px; margin-top: 12px; }
+.plan-actions .btn-plan-submit {
+  background: #7C6FA0;
+  color: var(--text-light);
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 9px 20px;
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+}
+.plan-actions .btn-plan-submit:hover { background: #6B5E90; }
+.plan-actions .btn-plan-submit:disabled { opacity: 0.5; cursor: not-allowed; }
+
+/* === Timestamps === */
+.event-time { font-size: 0.7rem; color: var(--text-muted); margin-top: 4px; }
+
+/* === Loading Indicator — TUI star spinner === */
+.msg-row.loading-row {
+  align-self: flex-start;
+  max-width: 82%;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 4px;
+  animation: msgIn 0.3s ease-out;
+}
+.tui-spinner {
+  font-size: 1.2rem;
+  color: var(--accent);
+  line-height: 1;
+  min-width: 1.2em;
+  transition: color 2s ease;
+}
+.stalled .tui-spinner { color: var(--red); }
+.tui-verb {
+  font-size: 0.88rem;
+  font-weight: 500;
+  transition: color 2s ease;
+}
+.stalled .tui-verb { color: var(--red); }
+
+/* Glimmer — reverse sweep highlight (same visual as TUI) */
+.glimmer-text {
+  background: linear-gradient(
+    90deg,
+    var(--text-secondary) 0%,
+    var(--text-secondary) 40%,
+    var(--accent) 50%,
+    var(--text-secondary) 60%,
+    var(--text-secondary) 100%
+  );
+  background-size: 200% 100%;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+  animation: glimmerSweep 3s ease-in-out infinite;
+}
+@keyframes glimmerSweep {
+  0%   { background-position: 100% 0; }
+  100% { background-position: -100% 0; }
+}
+.stalled .glimmer-text {
+  background: linear-gradient(
+    90deg,
+    var(--red) 0%,
+    var(--red) 40%,
+    #E06060 50%,
+    var(--red) 60%,
+    var(--red) 100%
+  );
+  background-size: 200% 100%;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+.tui-timer {
+  font-size: 0.78rem;
+  color: var(--text-muted);
+  font-family: var(--font-mono);
+  margin-left: auto;
+}

packages/remote-control-server/web/pages.css

@@ -0,0 +1,427 @@
+/* === Pages === */
+.page {
+  min-height: calc(100vh - 56px);
+  animation: pageIn var(--transition-slow) ease-out;
+}
+.page.no-nav { min-height: 100vh; }
+
+@keyframes pageIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* === Login — Anthropic === */
+#page-login {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  background:
+    radial-gradient(ellipse at 30% 20%, rgba(217, 119, 87, 0.06) 0%, transparent 50%),
+    radial-gradient(ellipse at 70% 80%, rgba(59, 138, 106, 0.04) 0%, transparent 50%),
+    var(--bg-primary);
+}
+
+.login-card {
+  background: var(--bg-card);
+  border-radius: 20px;
+  box-shadow: var(--shadow-lg);
+  padding: 48px 40px;
+  width: 100%;
+  max-width: 420px;
+  border: 1px solid var(--border-light);
+  animation: cardIn var(--transition-slow) ease-out;
+}
+
+@keyframes cardIn {
+  from { opacity: 0; transform: translateY(12px) scale(0.97); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+.login-header { text-align: center; margin-bottom: 36px; }
+.login-header h1 {
+  font-family: var(--font-display);
+  font-size: 1.6rem;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  margin-bottom: 6px;
+  color: var(--text-primary);
+}
+.subtitle {
+  color: var(--text-secondary);
+  font-size: 0.88rem;
+  font-weight: 400;
+}
+
+#login-form label {
+  display: block;
+  font-size: 0.8rem;
+  font-weight: 600;
+  margin-bottom: 8px;
+  color: var(--text-secondary);
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+#login-form input {
+  width: 100%;
+  padding: 12px 16px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-input);
+  font-size: 0.95rem;
+  color: var(--text-primary);
+  outline: none;
+  transition: all var(--transition-fast);
+  letter-spacing: 0.01em;
+}
+#login-form input:focus {
+  border-color: var(--accent);
+  background: var(--bg-input-focus);
+  box-shadow: 0 0 0 3px rgba(217, 119, 87, 0.12);
+}
+
+.error-msg {
+  color: var(--red);
+  font-size: 0.85rem;
+  margin-top: 10px;
+  padding: 8px 12px;
+  background: var(--red-bg);
+  border-radius: var(--radius-xs);
+}
+#login-btn { margin-top: 20px; width: 100%; padding: 13px; font-size: 0.95rem; }
+#login-form { margin-top: 24px; }
+
+/* === Dashboard — Anthropic === */
+.dashboard-container {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 40px 32px;
+}
+.dashboard-section { margin-bottom: 40px; }
+
+.section-title {
+  font-family: var(--font-display);
+  font-size: 1.15rem;
+  font-weight: 600;
+  margin-bottom: 16px;
+  color: var(--text-primary);
+  letter-spacing: -0.01em;
+}
+
+.section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 16px;
+}
+.section-header .section-title { margin-bottom: 0; }
+
+.card-list { display: flex; flex-direction: column; gap: 10px; }
+
+.empty-state {
+  color: var(--text-muted);
+  font-size: 0.9rem;
+  text-align: center;
+  padding: 40px 24px;
+  background: var(--bg-card);
+  border-radius: var(--radius);
+  border: 1.5px dashed var(--border);
+}
+
+/* Environment Card */
+.env-card {
+  background: var(--bg-card);
+  border-radius: var(--radius);
+  padding: 18px 24px;
+  box-shadow: var(--shadow-sm);
+  border: 1px solid var(--border-light);
+  display: grid;
+  grid-template-columns: 1fr auto;
+  align-items: center;
+  gap: 8px;
+  transition: all var(--transition-fast);
+}
+.env-card:hover {
+  box-shadow: var(--shadow);
+  border-color: var(--border);
+}
+.env-card .env-name {
+  font-weight: 600;
+  font-size: 0.95rem;
+  letter-spacing: -0.005em;
+}
+.env-card .env-dir {
+  font-family: var(--font-mono);
+  font-size: 0.78rem;
+  color: var(--text-secondary);
+}
+.env-card .env-branch {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+}
+
+/* Session Card */
+.session-card {
+  background: var(--bg-card);
+  border-radius: var(--radius);
+  padding: 16px 24px;
+  box-shadow: var(--shadow-sm);
+  border: 1px solid var(--border-light);
+  display: grid;
+  grid-template-columns: 1fr auto auto;
+  align-items: center;
+  gap: 16px;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+}
+.session-card:hover {
+  box-shadow: var(--shadow);
+  border-color: var(--accent);
+  transform: translateY(-1px);
+}
+.session-card:active { transform: translateY(0); }
+.session-card .session-title-text {
+  font-weight: 600;
+  font-size: 0.95rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  letter-spacing: -0.005em;
+}
+.session-card .session-id-text {
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  color: var(--text-muted);
+}
+
+/* === Session Detail — Anthropic === */
+.session-container {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 28px 32px;
+  display: flex;
+  flex-direction: column;
+  min-height: calc(100vh - 56px);
+}
+
+.back-link {
+  font-size: 0.85rem;
+  color: var(--text-secondary);
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  margin-bottom: 16px;
+  font-weight: 500;
+  transition: all var(--transition-fast);
+}
+.back-link:hover { color: var(--accent); text-decoration: none; }
+
+.session-header { margin-bottom: 24px; }
+
+.session-detail-title {
+  font-family: var(--font-display);
+  font-size: 1.25rem;
+  font-weight: 600;
+  margin-bottom: 8px;
+  letter-spacing: -0.01em;
+}
+.session-meta-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  align-items: center;
+}
+.meta-item {
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+  font-family: var(--font-mono);
+}
+
+/* === Control Bar — Claude-style === */
+.control-bar {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 20px 0;
+  border-top: 1px solid var(--border-light);
+  margin-top: auto;
+  flex-shrink: 0;
+}
+#msg-input {
+  flex: 1;
+  padding: 12px 18px;
+  border: 1.5px solid var(--border);
+  border-radius: 24px;
+  background: var(--bg-card);
+  font-size: 0.92rem;
+  color: var(--text-primary);
+  outline: none;
+  transition: all var(--transition-fast);
+  box-shadow: var(--shadow-sm);
+}
+#msg-input:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(217, 119, 87, 0.1), var(--shadow);
+}
+#msg-input::placeholder { color: var(--text-muted); }
+
+/* Circular action button */
+.action-btn {
+  width: 42px;
+  height: 42px;
+  border-radius: 50%;
+  border: none;
+  background: var(--accent);
+  color: var(--text-light);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  box-shadow: 0 2px 8px rgba(217, 119, 87, 0.25);
+}
+.action-btn:hover {
+  background: var(--accent-hover);
+  box-shadow: 0 3px 12px rgba(217, 119, 87, 0.35);
+  transform: translateY(-1px);
+}
+.action-btn:active {
+  transform: translateY(0);
+  box-shadow: none;
+}
+.action-btn.loading {
+  background: var(--red);
+  box-shadow: 0 2px 8px rgba(200, 60, 60, 0.25);
+}
+.action-btn.loading:hover {
+  background: #B33838;
+  box-shadow: 0 3px 12px rgba(200, 60, 60, 0.35);
+}
+.action-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
+}
+.action-btn svg { display: block; }
+
+/* === Responsive === */
+@media (max-width: 640px) {
+  .login-card { margin: 16px; padding: 32px 24px; }
+  .dashboard-container, .session-container { padding: 20px 16px; }
+  .session-card { grid-template-columns: 1fr; gap: 6px; }
+  .env-card { grid-template-columns: 1fr; }
+  .msg-row { max-width: 95%; }
+  .session-meta-row { flex-direction: column; gap: 4px; align-items: flex-start; }
+  .control-bar { flex-wrap: nowrap; }
+  #msg-input { min-width: 0; }
+  .identity-panel-inner { width: 100%; max-width: 100%; }
+}
+
+/* === Identity Panel (QR code + scan) === */
+.identity-panel {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.4);
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  animation: fadeIn var(--transition-fast) ease-out;
+}
+.identity-panel.hidden { display: none; }
+
+.identity-panel-inner {
+  background: var(--bg-card);
+  border-radius: var(--radius-lg, 20px);
+  box-shadow: var(--shadow-lg);
+  border: 1px solid var(--border-light);
+  width: 380px;
+  max-width: 90vw;
+  max-height: 90vh;
+  overflow-y: auto;
+  animation: cardIn var(--transition-slow) ease-out;
+}
+
+.identity-panel-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 20px 24px 16px;
+  border-bottom: 1px solid var(--border-light);
+}
+.identity-panel-header h3 {
+  font-family: var(--font-display);
+  font-size: 1.1rem;
+  font-weight: 600;
+  margin: 0;
+}
+.panel-close {
+  background: none;
+  border: none;
+  font-size: 1.5rem;
+  color: var(--text-secondary);
+  cursor: pointer;
+  padding: 0 4px;
+  line-height: 1;
+  transition: color var(--transition-fast);
+}
+.panel-close:hover { color: var(--text-primary); }
+
+.identity-panel-body {
+  padding: 20px 24px 24px;
+}
+.identity-section {
+  margin-bottom: 24px;
+}
+.identity-section:last-child { margin-bottom: 0; }
+.identity-section label {
+  display: block;
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 10px;
+}
+
+.uuid-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.uuid-text {
+  font-family: var(--font-mono);
+  font-size: 0.82rem;
+  color: var(--text-primary);
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm, 8px);
+  padding: 8px 12px;
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  user-select: all;
+}
+
+.qr-container {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  padding: 8px 0;
+}
+.qr-container canvas,
+.qr-container img {
+  display: block !important;
+  border-radius: var(--radius-sm, 8px);
+}
+
+#qr-scan-btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+}

packages/remote-control-server/web/render.js

@@ -0,0 +1,637 @@
+/**
+ * Remote Control — Event Rendering
+ *
+ * Renders session events into DOM elements for the event stream.
+ */
+
+import { esc } from "./utils.js";
+import { processAssistantEvent } from "./task-panel.js";
+
+// ============================================================
+// Replay state — tracks unresolved permission requests during history replay
+// ============================================================
+
+const replayPendingRequests = new Map();   // request_id → event data (unresolved)
+const replayRespondedRequests = new Set(); // request_ids that have a response
+
+/** Clear replay tracking state (call before each history load) */
+export function resetReplayState() {
+  replayPendingRequests.clear();
+  replayRespondedRequests.clear();
+}
+
+/** After replay finishes, render any still-unresolved permission prompts */
+export function renderReplayPendingRequests() {
+  if (replayPendingRequests.size === 0) return;
+
+  // Sort by seqNum to maintain order
+  const sorted = [...replayPendingRequests.entries()].sort((a, b) => (a[1].seqNum || 0) - (b[1].seqNum || 0));
+  for (const [, data] of sorted) {
+    // Re-invoke appendEvent without replay flag to go through the normal interactive path
+    appendEvent(data, { replay: false });
+  }
+  replayPendingRequests.clear();
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+function truncate(str, max) {
+  if (!str) return "";
+  const s = String(str);
+  return s.length > max ? s.slice(0, max) + "..." : s;
+}
+
+/**
+ * Extract plain text from an event payload.
+ * Server-side normalization guarantees payload.content is a string.
+ * Falls back to raw/message parsing for backward compat.
+ */
+export function extractText(payload) {
+  if (!payload) return "";
+
+  // Normalized format (server standardized)
+  if (typeof payload.content === "string" && payload.content) return payload.content;
+
+  // Fallback: raw message.content (child process format)
+  const msg = payload.message;
+  if (msg && typeof msg === "object") {
+    const mc = msg.content;
+    if (typeof mc === "string") return mc;
+    if (Array.isArray(mc)) {
+      return mc
+        .filter((b) => b && typeof b === "object" && b.type === "text")
+        .map((b) => b.text || "")
+        .join("");
+    }
+  }
+
+  // Final fallback
+  return typeof payload === "string" ? payload : JSON.stringify(payload);
+}
+
+function formatAssistantContent(content) {
+  let html = esc(content);
+  // Code blocks: ```...```
+  html = html.replace(/```(\w*)\n?([\s\S]*?)```/g, (_, lang, code) => {
+    return `<pre style="background:var(--bg-tool-card);padding:10px;border-radius:6px;overflow-x:auto;margin:6px 0;font-family:var(--font-mono);font-size:0.82rem;">${code.trim()}</pre>`;
+  });
+  // Inline code: `...`
+  html = html.replace(/`([^`]+)`/g, '<code style="background:var(--bg-tool-card);padding:2px 5px;border-radius:3px;font-family:var(--font-mono);font-size:0.85em;">$1</code>');
+  // Bold: **...**
+  html = html.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  return html;
+}
+
+// ============================================================
+// Event Router
+// ============================================================
+
+export function appendEvent(data, { replay = false } = {}) {
+  const stream = document.getElementById("event-stream");
+  if (!stream) return;
+
+  const type = data.type || "unknown";
+  const payload = data.payload || {};
+  const direction = data.direction || "inbound";
+
+  // Early filter: skip bridge init noise regardless of event type
+  const serialized = JSON.stringify(data);
+  if (/Remote Control connecting/i.test(serialized)) return;
+
+  // During history replay, only render messages & tools — skip interactive/stateful events
+  // Exception: unresolved permission/control requests are re-shown as pending prompts.
+  if (replay) {
+    let histEl;
+    switch (type) {
+      case "user":
+        if (direction === "outbound") histEl = renderUserMessage(payload, direction);
+        break;
+      case "assistant":
+        {
+          const text = extractText(payload);
+          if (text && text.trim()) histEl = renderAssistantMessage(payload);
+          processAssistantEvent(payload);
+        }
+        break;
+      case "tool_use":
+        histEl = renderToolUse(payload);
+        break;
+      case "tool_result":
+        histEl = renderToolResult(payload);
+        break;
+      case "error":
+        histEl = renderSystemMessage(`Error: ${payload.message || payload.content || "Unknown error"}`);
+        break;
+      case "control_request":
+      case "permission_request":
+        // Track unanswered permission/control requests for replay
+        if (payload.request && payload.request.subtype === "can_use_tool" && direction === "inbound") {
+          const rid = payload.request_id || data.id;
+          if (rid && !replayRespondedRequests.has(rid)) {
+            replayPendingRequests.set(rid, data);
+          }
+        }
+        return;
+      case "control_response":
+      case "permission_response":
+        // Mark the corresponding request as resolved
+        {
+          const respRid = payload.request_id;
+          if (respRid) {
+            replayRespondedRequests.add(respRid);
+            replayPendingRequests.delete(respRid);
+          }
+        }
+        return;
+      // Skip: partial_assistant, result, status, interrupt, system, user inbound echoes
+      default:
+        return;
+    }
+    if (histEl) {
+      stream.appendChild(histEl);
+      stream.scrollTop = stream.scrollHeight;
+    }
+    return;
+  }
+
+  let el;
+  let needLoading = false;
+
+  switch (type) {
+    case "user":
+      // Skip inbound user messages — they're echoes of what we already sent
+      if (direction === "inbound") return;
+      el = renderUserMessage(payload, direction);
+      needLoading = true;
+      break;
+    case "partial_assistant":
+      // Skip partial assistant — wait for the final "assistant" event
+      // to avoid blank/duplicate messages during streaming
+      return;
+    case "assistant":
+      removeLoading();
+      {
+        const text = extractText(payload);
+        if (text && text.trim()) el = renderAssistantMessage(payload);
+        processAssistantEvent(payload);
+      }
+      break;
+    case "result":
+    case "result_success":
+      removeLoading();
+      // Skip result — it just repeats the assistant message content
+      return;
+    case "tool_use":
+      el = renderToolUse(payload);
+      break;
+    case "tool_result":
+      el = renderToolResult(payload);
+      break;
+    case "control_request":
+    case "permission_request":
+      if (payload.request && payload.request.subtype === "can_use_tool") {
+        const toolName = payload.request.tool_name || "unknown";
+        const toolInput = payload.request.input || payload.request.tool_input || {};
+        if (toolName === "AskUserQuestion") {
+          el = renderAskUserQuestion({
+            request_id: payload.request_id || data.id,
+            tool_input: toolInput,
+            description: payload.request.description || "",
+          });
+        } else if (toolName === "ExitPlanMode") {
+          el = renderExitPlanMode({
+            request_id: payload.request_id || data.id,
+            tool_input: toolInput,
+            description: payload.request.description || "",
+          });
+        } else {
+          el = renderPermissionRequest({
+            request_id: payload.request_id || data.id,
+            tool_name: toolName,
+            tool_input: toolInput,
+            description: payload.request.description || "",
+          });
+        }
+      } else {
+        el = renderSystemMessage(`Control: ${payload.request?.subtype || "unknown"}`);
+      }
+      break;
+    case "control_response":
+    case "permission_response":
+      // Skip — these are just acknowledgments, no need to show in stream
+      return;
+    case "status":
+      // Skip connecting/waiting status noise from bridge
+      {
+        const msg = payload.message || payload.content || "";
+        const fullText = typeof payload === "string" ? payload : JSON.stringify(payload);
+        if (/connecting|waiting|initializing|Remote Control/i.test(msg + " " + fullText)) return;
+        if (!msg.trim()) return;
+        el = renderSystemMessage(msg);
+      }
+      break;
+    case "error":
+      removeLoading();
+      el = renderSystemMessage(`Error: ${payload.message || payload.content || "Unknown error"}`);
+      break;
+    case "interrupt":
+      removeLoading();
+      el = renderSystemMessage("Session interrupted");
+      break;
+    case "system":
+      // Skip raw system/init messages — they're noise
+      return;
+    default: {
+      // Skip noise from bridge init
+      const raw = JSON.stringify(payload);
+      if (/Remote Control connecting/i.test(raw)) return;
+      el = renderSystemMessage(`${type}: ${truncate(raw, 200)}`);
+    }
+  }
+
+  if (el) {
+    stream.appendChild(el);
+    stream.scrollTop = stream.scrollHeight;
+  }
+
+  // Show loading after the message element is in the DOM so it renders below
+  if (needLoading) showLoading();
+}
+
+// ============================================================
+// Renderers
+// ============================================================
+
+function renderUserMessage(payload, direction) {
+  const content = extractText(payload);
+  const row = document.createElement("div");
+  row.className = "msg-row user";
+  row.innerHTML = `<div class="msg-bubble">${esc(content)}</div>`;
+  return row;
+}
+
+function renderAssistantMessage(payload) {
+  const content = extractText(payload);
+  const row = document.createElement("div");
+  row.className = "msg-row assistant";
+  row.innerHTML = `<div class="msg-bubble">${formatAssistantContent(content)}</div>`;
+  return row;
+}
+
+function renderResult(payload) {
+  const text = payload.result || payload.subtype || "Session completed";
+  const row = document.createElement("div");
+  row.className = "msg-row system result";
+  row.innerHTML = `<div class="msg-bubble">✓ ${esc(text)}</div>`;
+  return row;
+}
+
+function renderToolUse(payload) {
+  const name = payload.tool_name || payload.name || "tool";
+  const input = payload.tool_input || payload.input || {};
+  const inputStr = typeof input === "string" ? input : JSON.stringify(input, null, 2);
+
+  const card = document.createElement("div");
+  card.className = "msg-row tool";
+  card.innerHTML = `
+    <div class="tool-card">
+      <div class="tool-card-header" onclick="this.nextElementSibling.classList.toggle('collapsed')">
+        <span class="tool-icon">&#9654;</span> Tool: <strong>${esc(name)}</strong>
+      </div>
+      <div class="tool-card-body collapsed">${esc(truncate(inputStr, 2000))}</div>
+    </div>`;
+  return card;
+}
+
+function renderToolResult(payload) {
+  const content = payload.content || payload.output || "";
+  const contentStr = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+
+  const card = document.createElement("div");
+  card.className = "msg-row tool";
+  card.innerHTML = `
+    <div class="tool-card">
+      <div class="tool-card-header" onclick="this.nextElementSibling.classList.toggle('collapsed')">
+        <span class="tool-icon">&#9654;</span> Tool Result
+      </div>
+      <div class="tool-card-body collapsed">${esc(truncate(contentStr, 2000))}</div>
+    </div>`;
+  return card;
+}
+
+export function renderPermissionRequest(payload) {
+  const requestId = payload.request_id || payload.id || "";
+  const toolName = payload.tool_name || "unknown";
+  const toolInput = payload.tool_input || payload.input || {};
+  const description = payload.description || "";
+  const inputStr = typeof toolInput === "string" ? toolInput : JSON.stringify(toolInput, null, 2);
+
+  const area = document.getElementById("permission-area");
+  area.classList.remove("hidden");
+
+  const el = document.createElement("div");
+  el.className = "permission-prompt";
+  el.dataset.requestId = requestId;
+  el.innerHTML = `
+    <div class="perm-title">Permission Request</div>
+    ${description ? `<div class="perm-desc">${esc(description)}</div>` : ""}
+    <div class="perm-tool-name"><strong>${esc(toolName)}</strong></div>
+    ${toolName !== "AskUserQuestion" ? `<div class="perm-tool">${esc(truncate(inputStr, 500))}</div>` : ""}
+    <div class="perm-actions">
+      <button class="btn-approve" onclick="window._approvePerm('${esc(requestId)}', this)">Approve</button>
+      <button class="btn-reject" onclick="window._rejectPerm('${esc(requestId)}', this)">Reject</button>
+    </div>`;
+  area.appendChild(el);
+
+  return renderSystemMessage(`Permission requested: ${toolName}`);
+}
+
+export function renderAskUserQuestion(payload) {
+  const requestId = payload.request_id || payload.id || "";
+  const questions = payload.tool_input?.questions || [];
+  const description = payload.description || "";
+
+  const area = document.getElementById("permission-area");
+  area.classList.remove("hidden");
+
+  const el = document.createElement("div");
+  el.className = "ask-panel";
+  el.dataset.requestId = requestId;
+
+  // Single question — no tabs needed
+  if (questions.length <= 1) {
+    const q = questions[0] || {};
+    const multiSelect = q.multiSelect || false;
+    el.innerHTML = `
+      <div class="ask-title">${esc(description || q.question || "Question")}</div>
+      <div class="ask-options">
+        ${(q.options || []).map((opt, j) => `
+          <button class="ask-option${multiSelect ? " ask-multi" : ""}" data-qidx="0" data-oidx="${j}"
+            onclick="window._selectOption(this, 0, ${j}, ${multiSelect})">
+            <span class="ask-option-label">${esc(opt.label || "")}</span>
+            ${opt.description ? `<span class="ask-option-desc">${esc(opt.description)}</span>` : ""}
+          </button>
+        `).join("")}
+        <div class="ask-other-row">
+          <input type="text" class="ask-other-input" data-qidx="0" placeholder="Other..." />
+          <button class="ask-other-btn" onclick="window._submitOther(this, 0)">Send</button>
+        </div>
+      </div>
+      <div class="ask-actions">
+        <button class="btn-approve" onclick="window._submitAnswers('${esc(requestId)}', this)">Submit</button>
+        <button class="btn-reject" onclick="window._rejectPerm('${esc(requestId)}', this)">Skip</button>
+      </div>`;
+  } else {
+    // Multiple questions — tab layout
+    const tabs = questions.map((q, i) => {
+      const multiSelect = q.multiSelect || false;
+      return `
+        <div class="ask-tab-page${i === 0 ? " active" : ""}" data-tab="${i}">
+          <div class="ask-question-text">${esc(q.question || "")}</div>
+          ${q.header ? `<div class="ask-header">${esc(q.header)}</div>` : ""}
+          <div class="ask-options">
+            ${(q.options || []).map((opt, j) => `
+              <button class="ask-option${multiSelect ? " ask-multi" : ""}" data-qidx="${i}" data-oidx="${j}"
+                onclick="window._selectOption(this, ${i}, ${j}, ${multiSelect})">
+                <span class="ask-option-label">${esc(opt.label || "")}</span>
+                ${opt.description ? `<span class="ask-option-desc">${esc(opt.description)}</span>` : ""}
+              </button>
+            `).join("")}
+            <div class="ask-other-row">
+              <input type="text" class="ask-other-input" data-qidx="${i}" placeholder="Other..." />
+              <button class="ask-other-btn" onclick="window._submitOther(this, ${i})">Send</button>
+            </div>
+          </div>
+        </div>`;
+    }).join("");
+
+    const tabBar = questions.map((q, i) =>
+      `<button class="ask-tab${i === 0 ? " active" : ""}" onclick="window._switchAskTab(this, ${i})">${esc(q.header || `Q${i + 1}`)}</button>`
+    ).join("");
+
+    el.innerHTML = `
+      <div class="ask-title">${esc(description || "Questions")}</div>
+      <div class="ask-tabs">${tabBar}</div>
+      ${tabs}
+      <div class="ask-tab-footer">
+        <span class="ask-progress">1 / ${questions.length}</span>
+        <div class="ask-actions">
+          <button class="btn-approve" onclick="window._submitAnswers('${esc(requestId)}', this)">Submit All</button>
+          <button class="btn-reject" onclick="window._rejectPerm('${esc(requestId)}', this)">Skip</button>
+        </div>
+      </div>`;
+  }
+  area.appendChild(el);
+
+  // Track selected options and store original questions for answer mapping
+  el._answers = {};
+  el._questions = questions;
+
+  return renderSystemMessage("Waiting for your response...");
+}
+
+export function renderExitPlanMode(payload) {
+  const requestId = payload.request_id || payload.id || "";
+  const toolInput = payload.tool_input || {};
+  const description = payload.description || "";
+  const planContent = toolInput.plan || "";
+
+  const area = document.getElementById("permission-area");
+  area.classList.remove("hidden");
+
+  const el = document.createElement("div");
+  el.className = "plan-panel";
+  el.dataset.requestId = requestId;
+
+  const isEmpty = !planContent || !planContent.trim();
+
+  if (isEmpty) {
+    el.innerHTML = `
+      <div class="plan-title">Exit plan mode?</div>
+      <div class="plan-options">
+        <button class="plan-option" data-value="yes-default" onclick="window._selectPlanOption(this, 'yes-default')">
+          <span class="plan-option-label">Yes</span>
+        </button>
+        <button class="plan-option" data-value="no" onclick="window._selectPlanOption(this, 'no')">
+          <span class="plan-option-label">No</span>
+        </button>
+      </div>
+      <div class="plan-actions">
+        <button class="btn-plan-submit" onclick="window._submitPlanResponse('${esc(requestId)}', this)">Submit</button>
+      </div>`;
+  } else {
+    el.innerHTML = `
+      <div class="plan-title">Ready to code?</div>
+      <div class="plan-content">${formatAssistantContent(planContent)}</div>
+      <div class="plan-options">
+        <button class="plan-option" data-value="yes-accept-edits" onclick="window._selectPlanOption(this, 'yes-accept-edits')">
+          <span class="plan-option-label">Yes, auto-accept edits</span>
+          <span class="plan-option-desc">Approve plan and auto-accept file edits</span>
+        </button>
+        <button class="plan-option" data-value="yes-default" onclick="window._selectPlanOption(this, 'yes-default')">
+          <span class="plan-option-label">Yes, manually approve edits</span>
+          <span class="plan-option-desc">Approve plan but confirm each edit</span>
+        </button>
+        <button class="plan-option" data-value="no" onclick="window._selectPlanOption(this, 'no')">
+          <span class="plan-option-label">No, keep planning</span>
+          <span class="plan-option-desc">Provide feedback to refine the plan</span>
+        </button>
+      </div>
+      <div class="plan-feedback-area" data-for="no">
+        <textarea class="plan-feedback-input" placeholder="Tell Claude what to change..."></textarea>
+      </div>
+      <div class="plan-actions">
+        <button class="btn-plan-submit" onclick="window._submitPlanResponse('${esc(requestId)}', this)">Submit</button>
+      </div>`;
+  }
+
+  area.appendChild(el);
+
+  el._selectedValue = null;
+  el._planContent = planContent;
+  el._isEmpty = isEmpty;
+
+  return renderSystemMessage("Waiting for your response...");
+}
+
+function renderSystemMessage(text) {
+  const row = document.createElement("div");
+  row.className = "msg-row system";
+  row.innerHTML = `<div class="msg-bubble">${esc(text)}</div>`;
+  return row;
+}
+
+// ============================================================
+// Loading Indicator — TUI star spinner style
+// ============================================================
+
+const LOADING_ID = "loading-indicator";
+
+// TUI star spinner frames (same as Claude Code CLI)
+const SPINNER_FRAMES = ["·", "✢", "✳", "✶", "✻", "✽"];
+const SPINNER_CYCLE = [...SPINNER_FRAMES, ...SPINNER_FRAMES.slice().reverse()];
+
+// 204 verbs from TUI src/constants/spinnerVerbs.ts
+const SPINNER_VERBS = [
+  "Accomplishing","Actioning","Actualizing","Architecting","Baking","Beaming",
+  "Beboppin'","Befuddling","Billowing","Blanching","Bloviating","Boogieing",
+  "Boondoggling","Booping","Bootstrapping","Brewing","Bunning","Burrowing",
+  "Calculating","Canoodling","Caramelizing","Cascading","Catapulting","Cerebrating",
+  "Channeling","Channelling","Choreographing","Churning","Clauding","Coalescing",
+  "Cogitating","Combobulating","Composing","Computing","Concocting","Considering",
+  "Contemplating","Cooking","Crafting","Creating","Crunching","Crystallizing",
+  "Cultivating","Deciphering","Deliberating","Determining","Dilly-dallying",
+  "Discombobulating","Doing","Doodling","Drizzling","Ebbing","Effecting",
+  "Elucidating","Embellishing","Enchanting","Envisioning","Evaporating",
+  "Fermenting","Fiddle-faddling","Finagling","Flambéing","Flibbertigibbeting",
+  "Flowing","Flummoxing","Fluttering","Forging","Forming","Frolicking","Frosting",
+  "Gallivanting","Galloping","Garnishing","Generating","Gesticulating",
+  "Germinating","Gitifying","Grooving","Gusting","Harmonizing","Hashing",
+  "Hatching","Herding","Honking","Hullaballooing","Hyperspacing","Ideating",
+  "Imagining","Improvising","Incubating","Inferring","Infusing","Ionizing",
+  "Jitterbugging","Julienning","Kneading","Leavening","Levitating","Lollygagging",
+  "Manifesting","Marinating","Meandering","Metamorphosing","Misting","Moonwalking",
+  "Moseying","Mulling","Mustering","Musing","Nebulizing","Nesting","Newspapering",
+  "Noodling","Nucleating","Orbiting","Orchestrating","Osmosing","Perambulating",
+  "Percolating","Perusing","Philosophising","Photosynthesizing","Pollinating",
+  "Pondering","Pontificating","Pouncing","Precipitating","Prestidigitating",
+  "Processing","Proofing","Propagating","Puttering","Puzzling","Quantumizing",
+  "Razzle-dazzling","Razzmatazzing","Recombobulating","Reticulating","Roosting",
+  "Ruminating","Sautéing","Scampering","Schlepping","Scurrying","Seasoning",
+  "Shenaniganing","Shimmying","Simmering","Skedaddling","Sketching","Slithering",
+  "Smooshing","Sock-hopping","Spelunking","Spinning","Sprouting","Stewing",
+  "Sublimating","Swirling","Swooping","Symbioting","Synthesizing","Tempering",
+  "Thinking","Thundering","Tinkering","Tomfoolering","Topsy-turvying",
+  "Transfiguring","Transmuting","Twisting","Undulating","Unfurling","Unravelling",
+  "Vibing","Waddling","Wandering","Warping","Whatchamacalliting","Whirlpooling",
+  "Whirring","Whisking","Wibbling","Working","Wrangling","Zesting","Zigzagging",
+];
+
+// Animation state
+let spinnerInterval = null;
+let timerInterval = null;
+let stalledCheckInterval = null;
+let spinnerFrame = 0;
+let loadingStartTime = 0;
+let lastActivityTime = 0;
+let isStalled = false;
+let loadingActive = false;
+
+export function isLoading() {
+  return loadingActive;
+}
+
+function syncActionBtn(state) {
+  if (typeof window.__updateActionBtn === "function") window.__updateActionBtn(state);
+}
+
+export function showLoading() {
+  removeLoading();
+  const stream = document.getElementById("event-stream");
+  if (!stream) return;
+
+  loadingActive = true;
+  syncActionBtn(true);
+
+  const verb = SPINNER_VERBS[Math.floor(Math.random() * SPINNER_VERBS.length)];
+  loadingStartTime = Date.now();
+  lastActivityTime = Date.now();
+  isStalled = false;
+
+  const el = document.createElement("div");
+  el.id = LOADING_ID;
+  el.className = "msg-row loading-row";
+  el.innerHTML = `<span class="tui-spinner">${SPINNER_CYCLE[0]}</span><span class="tui-verb glimmer-text">${esc(verb)}…</span><span class="tui-timer">0s</span>`;
+  stream.appendChild(el);
+  stream.scrollTop = stream.scrollHeight;
+
+  const spinnerEl = el.querySelector(".tui-spinner");
+  const timerEl = el.querySelector(".tui-timer");
+  const loadingEl = el;
+
+  // Spinner animation — 120ms interval, same as TUI
+  spinnerFrame = 0;
+  spinnerInterval = setInterval(() => {
+    spinnerFrame = (spinnerFrame + 1) % SPINNER_CYCLE.length;
+    if (spinnerEl) spinnerEl.textContent = SPINNER_CYCLE[spinnerFrame];
+  }, 120);
+
+  // Timer — update every second
+  timerInterval = setInterval(() => {
+    if (timerEl) {
+      const elapsed = Math.floor((Date.now() - loadingStartTime) / 1000);
+      timerEl.textContent = `${elapsed}s`;
+    }
+  }, 1000);
+
+  // Stalled detection — check every 120ms (aligned with spinner)
+  stalledCheckInterval = setInterval(() => {
+    if (!isStalled && Date.now() - lastActivityTime > 3000) {
+      isStalled = true;
+      if (loadingEl) loadingEl.classList.add("stalled");
+    }
+  }, 120);
+}
+
+export function removeLoading() {
+  if (spinnerInterval) { clearInterval(spinnerInterval); spinnerInterval = null; }
+  if (timerInterval) { clearInterval(timerInterval); timerInterval = null; }
+  if (stalledCheckInterval) { clearInterval(stalledCheckInterval); stalledCheckInterval = null; }
+  isStalled = false;
+  loadingActive = false;
+  syncActionBtn(false);
+  const el = document.getElementById(LOADING_ID);
+  if (el) el.remove();
+}
+
+/** Reset stalled timer — call when SSE events arrive */
+export function refreshLoadingActivity() {
+  lastActivityTime = Date.now();
+  if (isStalled) {
+    isStalled = false;
+    const loadingEl = document.getElementById(LOADING_ID);
+    if (loadingEl) loadingEl.classList.remove("stalled");
+  }
+}

packages/remote-control-server/web/sse.js

@@ -0,0 +1,53 @@
+/**
+ * Remote Control — SSE Connection Manager (UUID-based auth)
+ */
+import { getUuid } from "./api.js";
+import { refreshLoadingActivity } from "./render.js";
+
+let currentEventSource = null;
+let currentSSESessionId = null;
+let onEventCallback = null;
+
+export function connectSSE(sessionId, onEvent, fromSeqNum = 0) {
+  disconnectSSE();
+  currentSSESessionId = sessionId;
+  onEventCallback = onEvent;
+
+  const uuid = getUuid();
+  let url = `/web/sessions/${sessionId}/events?uuid=${encodeURIComponent(uuid)}`;
+
+  const es = new EventSource(url);
+  currentEventSource = es;
+
+  // Track the last sequence number we've seen to avoid duplicates
+  let lastSeenSeq = fromSeqNum;
+
+  es.addEventListener("message", (e) => {
+    try {
+      const data = JSON.parse(e.data);
+      // Skip events we've already rendered from history
+      if (data.seqNum !== undefined && data.seqNum <= lastSeenSeq) return;
+      if (data.seqNum !== undefined) lastSeenSeq = data.seqNum;
+      onEventCallback?.(data);
+      refreshLoadingActivity();
+    } catch {
+      // ignore parse errors
+    }
+  });
+
+  es.addEventListener("error", () => {
+    // EventSource auto-reconnects
+  });
+}
+
+export function disconnectSSE() {
+  if (currentEventSource) {
+    currentEventSource.close();
+    currentEventSource = null;
+    currentSSESessionId = null;
+  }
+}
+
+export function getCurrentSSESessionId() {
+  return currentSSESessionId;
+}

packages/remote-control-server/web/style.css

@@ -0,0 +1,6 @@
+/* Main stylesheet — imports all modules */
+@import url('./base.css');
+@import url('./components.css');
+@import url('./pages.css');
+@import url('./messages.css');
+@import url('./task-panel.css');

packages/remote-control-server/web/task-panel.css

@@ -0,0 +1,275 @@
+/* === Task/Todo Floating Panel — Anthropic === */
+
+/* Panel container */
+.task-panel {
+  position: fixed;
+  right: 0;
+  top: 56px;
+  bottom: 0;
+  width: 340px;
+  background: var(--bg-card);
+  border-left: 1px solid var(--border-light);
+  box-shadow: -4px 0 20px rgba(0, 0, 0, 0.06);
+  z-index: 90;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  transition: transform var(--transition-base, 0.2s) ease, opacity var(--transition-base, 0.2s) ease;
+}
+.task-panel.hidden {
+  transform: translateX(100%);
+  opacity: 0;
+  pointer-events: none;
+}
+.task-panel.visible {
+  transform: translateX(0);
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* Main content shifts left when panel is open */
+.session-container.panel-open {
+  margin-right: 340px;
+  transition: margin-right var(--transition-base, 0.2s) ease;
+}
+
+/* Header */
+.tp-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 20px 12px;
+  border-bottom: 1px solid var(--border-light);
+  flex-shrink: 0;
+}
+.tp-title {
+  font-family: var(--font-display, "Bricolage Grotesque", sans-serif);
+  font-size: 0.95rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  color: var(--text-primary);
+}
+.tp-close-btn {
+  background: none;
+  border: none;
+  font-size: 1.3rem;
+  color: var(--text-secondary);
+  cursor: pointer;
+  padding: 0 4px;
+  line-height: 1;
+  transition: color var(--transition-fast, 0.12s);
+}
+.tp-close-btn:hover { color: var(--text-primary); }
+
+/* Scrollable body */
+.tp-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0;
+}
+
+/* Empty state */
+.tp-empty {
+  color: var(--text-muted);
+  font-size: 0.85rem;
+  text-align: center;
+  padding: 48px 24px;
+}
+
+/* Progress bar */
+.tp-progress {
+  position: relative;
+  height: 28px;
+  background: var(--bg-input, #f5f1eb);
+  margin: 12px 16px;
+  border-radius: 6px;
+  overflow: hidden;
+}
+.tp-progress-bar {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  background: var(--green, #3b8a6a);
+  border-radius: 6px;
+  transition: width 0.3s ease;
+  opacity: 0.2;
+}
+.tp-progress-label {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  letter-spacing: 0.01em;
+}
+
+/* Section */
+.tp-section {
+  border-top: 1px solid var(--border-light);
+}
+.tp-section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 16px 6px;
+}
+.tp-section-title {
+  font-size: 0.78rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-secondary);
+}
+.tp-section-stats {
+  display: flex;
+  gap: 8px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+.tp-stat-dim {
+  color: var(--text-muted);
+  font-weight: 400;
+  margin-left: 2px;
+}
+.tp-section-body {
+  padding: 4px 12px 12px;
+}
+
+/* Task/Todo item */
+.tp-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 8px 6px;
+  border-radius: 6px;
+  transition: background var(--transition-fast, 0.12s);
+}
+.tp-item:hover {
+  background: var(--bg-input, #f5f1eb);
+}
+
+/* Status icon */
+.tp-item-icon {
+  flex-shrink: 0;
+  width: 20px;
+  height: 20px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.85rem;
+  margin-top: 1px;
+}
+.tp-icon-done {
+  color: var(--green, #3b8a6a);
+}
+.tp-icon-active {
+  color: var(--accent, #d97757);
+  animation: tpPulse 1.5s ease-in-out infinite;
+}
+.tp-icon-pending {
+  color: var(--text-muted);
+}
+.tp-icon-deleted {
+  color: var(--red, #c83c3c);
+}
+
+@keyframes tpPulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+/* Item content */
+.tp-item-content {
+  flex: 1;
+  min-width: 0;
+}
+.tp-item-subject {
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text-primary);
+  line-height: 1.35;
+  word-break: break-word;
+}
+.tp-status-completed .tp-item-subject {
+  text-decoration: line-through;
+  color: var(--text-muted);
+}
+.tp-status-deleted .tp-item-subject {
+  text-decoration: line-through;
+  color: var(--text-muted);
+  opacity: 0.5;
+}
+.tp-blocked .tp-item-subject {
+  opacity: 0.55;
+}
+
+/* Active form (spinner text) */
+.tp-item-active {
+  font-size: 0.78rem;
+  color: var(--accent, #d97757);
+  margin-top: 2px;
+  font-style: italic;
+}
+
+/* Blocked indicator */
+.tp-item-blocked {
+  font-size: 0.72rem;
+  color: var(--text-muted);
+  margin-top: 3px;
+  font-family: var(--font-mono, "Fira Code", monospace);
+}
+
+/* Owner badge */
+.tp-item-owner {
+  flex-shrink: 0;
+  font-size: 0.72rem;
+  color: var(--text-muted);
+  background: var(--bg-input, #f5f1eb);
+  padding: 2px 8px;
+  border-radius: 10px;
+  margin-top: 2px;
+  white-space: nowrap;
+}
+
+/* Toggle badge in nav */
+.task-count-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  font-size: 0.68rem;
+  font-weight: 700;
+  line-height: 1;
+  color: var(--text-light, #fff);
+  background: var(--accent, #d97757);
+  border-radius: 9px;
+  margin-left: 4px;
+  vertical-align: middle;
+}
+.task-count-badge.hidden { display: none; }
+
+/* Active toggle button state */
+#task-panel-toggle.active {
+  color: var(--accent, #d97757);
+  background: rgba(217, 119, 87, 0.08);
+}
+
+/* === Responsive === */
+@media (max-width: 640px) {
+  .task-panel {
+    width: 100%;
+    top: 0;
+    z-index: 200;
+  }
+  .session-container.panel-open {
+    margin-right: 0;
+  }
+}

packages/remote-control-server/web/task-panel.js

@@ -0,0 +1,400 @@
+/**
+ * Remote Control — Task/Todo Floating Panel
+ *
+ * Parses tool_use blocks from assistant events to extract TaskCreate,
+ * TaskUpdate, and TodoWrite operations, then renders a floating panel
+ * showing the current task/todo state.
+ */
+
+// ============================================================
+// State
+// ============================================================
+
+/** @type {Map<string, TaskItem>} V2 Tasks keyed by id */
+const tasks = new Map();
+
+/** @type {TodoItem[]} V1 Todos */
+let todos = [];
+
+/** @type {boolean} Panel visibility */
+let panelVisible = false;
+
+/** @type {HTMLElement|null} Panel root element */
+let panelEl = null;
+
+/** @type {HTMLElement|null} Badge element showing count */
+let badgeEl = null;
+
+// ============================================================
+// Types (JSDoc for clarity)
+// ============================================================
+
+/**
+ * @typedef {Object} TaskItem
+ * @property {string} id
+ * @property {string} subject
+ * @property {string} description
+ * @property {string} [activeForm]
+ * @property {'pending'|'in_progress'|'completed'|'deleted'} status
+ * @property {string} [owner]
+ * @property {string[]} blocks
+ * @property {string[]} blockedBy
+ */
+
+/**
+ * @typedef {Object} TodoItem
+ * @property {string} content
+ * @property {'pending'|'in_progress'|'completed'} status
+ * @property {string} activeForm
+ */
+
+// ============================================================
+// State mutations
+// ============================================================
+
+/**
+ * Process an assistant event payload, extracting tool_use blocks.
+ * @param {{ message?: { content?: unknown } }} payload
+ */
+export function processAssistantEvent(payload) {
+  if (!payload || !payload.message) return;
+
+  const content = payload.message.content;
+  if (!Array.isArray(content)) return;
+
+  let changed = false;
+
+  for (const block of content) {
+    if (!block || typeof block !== "object" || block.type !== "tool_use") continue;
+
+    const name = block.name;
+    const input = block.input || {};
+
+    if (name === "TaskCreate") {
+      handleTaskCreate(input);
+      changed = true;
+    } else if (name === "TaskUpdate") {
+      handleTaskUpdate(input);
+      changed = true;
+    } else if (name === "TodoWrite") {
+      handleTodoWrite(input);
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    renderPanel();
+    updateBadge();
+  }
+}
+
+/**
+ * @param {{ subject?: string, description?: string, activeForm?: string, metadata?: object }} input
+ */
+function handleTaskCreate(input) {
+  // TaskCreate creates a task; the tool itself generates the ID server-side.
+  // We extract from the tool output (tool_result) if available, or use a
+  // synthetic ID. The actual ID comes from the tool result event.
+  // Since we only see tool_use (not tool_result here), we create with a
+  // temporary key based on subject and let TaskUpdate resolve it.
+  const subject = input.subject || "Untitled task";
+  const description = input.description || "";
+  const activeForm = input.activeForm;
+
+  // Check if there's an id in the input (some versions include it)
+  const id = input.taskId || input.id || `task_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+  tasks.set(id, {
+    id,
+    subject,
+    description,
+    activeForm,
+    status: "pending",
+    owner: undefined,
+    blocks: [],
+    blockedBy: [],
+  });
+}
+
+/**
+ * @param {{ taskId?: string, status?: string, subject?: string, description?: string, activeForm?: string, owner?: string, addBlocks?: string[], addBlockedBy?: string[], metadata?: object }} input
+ */
+function handleTaskUpdate(input) {
+  const id = input.taskId;
+  if (!id) return;
+
+  const existing = tasks.get(id);
+  if (!existing) {
+    // Task wasn't tracked yet — create it from the update
+    tasks.set(id, {
+      id,
+      subject: input.subject || "Untitled task",
+      description: input.description || "",
+      activeForm: input.activeForm,
+      status: input.status || "pending",
+      owner: input.owner,
+      blocks: [],
+      blockedBy: [],
+    });
+    return;
+  }
+
+  if (input.subject !== undefined) existing.subject = input.subject;
+  if (input.description !== undefined) existing.description = input.description;
+  if (input.activeForm !== undefined) existing.activeForm = input.activeForm;
+  if (input.status !== undefined) existing.status = input.status;
+  if (input.owner !== undefined) existing.owner = input.owner;
+  if (input.addBlocks) {
+    existing.blocks = [...new Set([...existing.blocks, ...input.addBlocks])];
+  }
+  if (input.addBlockedBy) {
+    existing.blockedBy = [...new Set([...existing.blockedBy, ...input.addBlockedBy])];
+  }
+  if (input.status === "deleted") {
+    tasks.delete(id);
+  }
+}
+
+/**
+ * @param {{ todos?: Array<{ content: string, status: string, activeForm: string }> }} input
+ */
+function handleTodoWrite(input) {
+  if (!Array.isArray(input.todos)) return;
+  todos = input.todos.map((t) => ({
+    content: t.content || "",
+    status: t.status || "pending",
+    activeForm: t.activeForm || "",
+  }));
+}
+
+// ============================================================
+// Public API
+// ============================================================
+
+/**
+ * Reset all state (call when switching sessions).
+ */
+export function resetTaskState() {
+  tasks.clear();
+  todos = [];
+  if (panelEl) panelEl.innerHTML = "";
+  updateBadge();
+}
+
+/**
+ * Get current state for debugging.
+ */
+export function getTaskState() {
+  return { tasks: [...tasks.values()], todos };
+}
+
+/**
+ * Initialize the task panel DOM.
+ * @param {HTMLElement} container
+ */
+export function initTaskPanel(container) {
+  if (panelEl) return; // already initialized
+  panelEl = container;
+  badgeEl = document.getElementById("task-badge");
+  renderPanel();
+}
+
+/**
+ * Toggle panel visibility.
+ */
+export function toggleTaskPanel() {
+  panelVisible = !panelVisible;
+  if (panelEl) {
+    panelEl.classList.toggle("hidden", !panelVisible);
+    panelEl.classList.toggle("visible", panelVisible);
+  }
+  // Adjust main content margin
+  const sessionContainer = document.querySelector(".session-container");
+  if (sessionContainer) {
+    sessionContainer.classList.toggle("panel-open", panelVisible);
+  }
+  // Toggle active state on the nav button
+  const toggleBtn = document.getElementById("task-panel-toggle");
+  if (toggleBtn) {
+    toggleBtn.classList.toggle("active", panelVisible);
+  }
+}
+
+/**
+ * Show the panel.
+ */
+export function showTaskPanel() {
+  if (!panelVisible) toggleTaskPanel();
+}
+
+/**
+ * Hide the panel.
+ */
+export function hideTaskPanel() {
+  if (panelVisible) toggleTaskPanel();
+}
+
+// ============================================================
+// Rendering
+// ============================================================
+
+function esc(str) {
+  if (!str) return "";
+  const d = document.createElement("div");
+  d.textContent = String(str);
+  return d.innerHTML;
+}
+
+function renderPanel() {
+  if (!panelEl) return;
+
+  const allTasks = [...tasks.values()];
+  const hasTasks = allTasks.length > 0;
+  const hasTodos = todos.length > 0;
+
+  if (!hasTasks && !hasTodos) {
+    panelEl.innerHTML = `<div class="tp-empty">No tasks or todos yet</div>`;
+    return;
+  }
+
+  const parts = [];
+
+  // Progress summary
+  const totalItems = allTasks.length + todos.length;
+  const completedTasks = allTasks.filter((t) => t.status === "completed").length;
+  const completedTodos = todos.filter((t) => t.status === "completed").length;
+  const completedTotal = completedTasks + completedTodos;
+  const pct = totalItems > 0 ? Math.round((completedTotal / totalItems) * 100) : 0;
+
+  parts.push(`
+    <div class="tp-progress">
+      <div class="tp-progress-bar" style="width:${pct}%"></div>
+      <span class="tp-progress-label">${completedTotal}/${totalItems} completed</span>
+    </div>
+  `);
+
+  // V2 Tasks section
+  if (hasTasks) {
+    const inProgress = allTasks.filter((t) => t.status === "in_progress").length;
+    const pending = allTasks.filter((t) => t.status === "pending").length;
+    const completed = allTasks.filter((t) => t.status === "completed").length;
+    parts.push(`
+      <div class="tp-section">
+        <div class="tp-section-header">
+          <span class="tp-section-title">Tasks</span>
+          <span class="tp-section-stats">
+            ${completed}<span class="tp-stat-dim">done</span>
+            ${inProgress > 0 ? `${inProgress}<span class="tp-stat-dim">active</span>` : ""}
+            ${pending > 0 ? `${pending}<span class="tp-stat-dim">open</span>` : ""}
+          </span>
+        </div>
+        <div class="tp-section-body">
+          ${allTasks.map(renderTaskItem).join("")}
+        </div>
+      </div>
+    `);
+  }
+
+  // V1 Todos section
+  if (hasTodos) {
+    const inProgress = todos.filter((t) => t.status === "in_progress").length;
+    const pending = todos.filter((t) => t.status === "pending").length;
+    const completed = todos.filter((t) => t.status === "completed").length;
+    parts.push(`
+      <div class="tp-section">
+        <div class="tp-section-header">
+          <span class="tp-section-title">Todos</span>
+          <span class="tp-section-stats">
+            ${completed}<span class="tp-stat-dim">done</span>
+            ${inProgress > 0 ? `${inProgress}<span class="tp-stat-dim">active</span>` : ""}
+            ${pending > 0 ? `${pending}<span class="tp-stat-dim">open</span>` : ""}
+          </span>
+        </div>
+        <div class="tp-section-body">
+          ${todos.map(renderTodoItem).join("")}
+        </div>
+      </div>
+    `);
+  }
+
+  panelEl.innerHTML = `
+    <div class="tp-header">
+      <span class="tp-title">Tasks & Todos</span>
+      <button class="tp-close-btn" onclick="window.__toggleTaskPanel()">&times;</button>
+    </div>
+    <div class="tp-body">${parts.join("")}</div>
+  `;
+}
+
+/**
+ * @param {TaskItem} task
+ */
+function renderTaskItem(task) {
+  const icon = statusIcon(task.status);
+  const isBlocked = task.blockedBy.length > 0 && task.status !== "completed";
+  const cls = [
+    "tp-item",
+    `tp-status-${task.status}`,
+    isBlocked ? "tp-blocked" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return `
+    <div class="${cls}">
+      <span class="tp-item-icon ${icon.cls}">${icon.char}</span>
+      <div class="tp-item-content">
+        <div class="tp-item-subject">${esc(task.subject)}</div>
+        ${task.activeForm && task.status === "in_progress" ? `<div class="tp-item-active">${esc(task.activeForm)}...</div>` : ""}
+        ${isBlocked ? `<div class="tp-item-blocked">blocked by ${task.blockedBy.map((id) => `#${esc(id)}`).join(", ")}</div>` : ""}
+      </div>
+      ${task.owner ? `<span class="tp-item-owner">@${esc(task.owner)}</span>` : ""}
+    </div>
+  `;
+}
+
+/**
+ * @param {TodoItem} todo
+ */
+function renderTodoItem(todo) {
+  const icon = statusIcon(todo.status);
+  const cls = ["tp-item", `tp-status-${todo.status}`].join(" ");
+
+  return `
+    <div class="${cls}">
+      <span class="tp-item-icon ${icon.cls}">${icon.char}</span>
+      <div class="tp-item-content">
+        <div class="tp-item-subject">${esc(todo.content)}</div>
+        ${todo.activeForm && todo.status === "in_progress" ? `<div class="tp-item-active">${esc(todo.activeForm)}...</div>` : ""}
+      </div>
+    </div>
+  `;
+}
+
+/**
+ * @param {string} status
+ * @returns {{ char: string, cls: string }}
+ */
+function statusIcon(status) {
+  switch (status) {
+    case "completed":
+      return { char: "\u2713", cls: "tp-icon-done" };
+    case "in_progress":
+      return { char: "\u25CF", cls: "tp-icon-active" };
+    case "deleted":
+      return { char: "\u2717", cls: "tp-icon-deleted" };
+    default:
+      return { char: "\u25CB", cls: "tp-icon-pending" };
+  }
+}
+
+function updateBadge() {
+  if (!badgeEl) return;
+  const total = tasks.size + todos.length;
+  if (total > 0) {
+    badgeEl.textContent = String(total);
+    badgeEl.classList.remove("hidden");
+  } else {
+    badgeEl.classList.add("hidden");
+  }
+}

packages/remote-control-server/web/utils.js

@@ -0,0 +1,27 @@
+/**
+ * Remote Control — Shared Utilities
+ */
+
+export function esc(str) {
+  if (!str) return "";
+  const div = document.createElement("div");
+  div.textContent = String(str);
+  return div.innerHTML;
+}
+
+export function formatTime(ts) {
+  if (!ts) return "";
+  return new Date(ts * 1000).toLocaleString();
+}
+
+export function statusClass(status) {
+  const map = {
+    active: "active",
+    running: "running",
+    idle: "idle",
+    requires_action: "requires_action",
+    archived: "archived",
+    error: "error",
+  };
+  return map[status] || "default";
+}