dsh-device-fleet 0.1.0-dev.12 → 0.1.0-dev.14

package/docs/notes/dev-release.md

@@ -39,19 +39,19 @@ dsh plugin --profile desktop add dsh-device-fleet@dev
 - 邀请里新增 `endpoints`（创建者的局域网/热点 IPv4 + direct 端口），加入方重启后自动向这些地址回连，绕开组播发现失败；
 - 新增 `fleet_status`（deviceId/直连端口/发现/连接/roster/hints）与 `fleet_connect(host, port)`（手动直连，成功后会从握手学到对端 deviceId）；
 - `fleet_list` 仍是本地视图；配对成功后双方 roster 会自动固定对端公钥。
-## 0.1.0-dev.11（稳定化）
+## 0.1.0-dev.13（稳定化）
 
 - 直连端口可固定（profile `direct.port`），插件重载不再换端口；
 - 连接断开后自动重试已知地址（不再只在启动时试一次）；
 - `fleet_connect` 手动地址会持久化到 `peer-hints.json`，重启后继续回连；
 - 新增 `fleet_delegate`（dev.5）：目标设备用 `SubagentProvider` + `delivery:'caller'` 跑 agent 并返回最终结果。
-## 0.1.0-dev.11（审批收件箱，逻辑层）
+## 0.1.0-dev.13（审批收件箱，逻辑层）
 
 - 新增 `ApprovalInbox`：ask 档请求排队、超时 fail-closed、approve（once/ttl）/deny、关闭时全部失败关闭；
 - 直调与委派的 ask 档改为等待本机收件箱结果（不再一律拒绝）；
 - 新工具：`fleet_approvals` / `fleet_approve` / `fleet_deny`；`fleet_simulate_request`（仅 `approvals.simulation: true`）用于本机无第二台设备时演练流程；
 - 审批面板（Client UI）与通知尚未实现，当前通过工具/后续 UI 应答。
-## 0.1.0-dev.11（Room 逻辑层，本机模拟）
+## 0.1.0-dev.13（Room 逻辑层，本机模拟）
 
 - `RoomService`：当前会话升级为 Room Host；本地模拟参与者（真实 DSH session/agent）；
 - 寻址消息：`room_send` 只唤醒被点名成员，Host 会话写权威 `room/message` 事件；
@@ -59,13 +59,13 @@ dsh plugin --profile desktop add dsh-device-fleet@dev
 - Room Board：`room_task_add/update/list`，`dependsOn` 串行交接（前置完成时唤醒下一个 owner），无依赖任务并行不受影响；
 - 工具：`room_create / room_add_local / room_remove_member / room_send / room_messages / room_status / room_task_* / room_close`；
 - 远程参与者传输与 Client UI 未做（下一步）。
-## 0.1.0-dev.11（审批面板 UI，第一版）
+## 0.1.0-dev.13（审批面板 UI，第一版）
 
 - Host 新增本地 HTTP 数据面：GET `/device-fleet/approvals`、POST `/device-fleet/approvals/decide`（仅本机 web 载体，决策仍走 ApprovalInbox）；
 - Client half：`client.js` 闭包工厂，注册 `shell.overlay` 浮动「Fleet 审批」按钮 + 面板，轮询待审批列表，支持允许一次 / 允许 15 分钟 / 拒绝；
 - package.json 增加 `dsh.client` 与 `./client` 导出；`files` 增加 client.js；
 - Client 视觉验证需要刷新页面；当前无浏览器控制，仅验证了 bundle 语法与 Host 路由注册。
-## 0.1.0-dev.11（审批入口不遮挡）
+## 0.1.0-dev.13（审批入口不遮挡）
 
 - 触发按钮从右下角浮动改为 `sidebar.footer.action`（设置旁边），不再遮挡任务列表/内容面板；
 - 审批 inbox 改为点击后居中的模态对话框（带遮罩，Esc/点遮罩关闭）；

package/docs/notes/fleet-console-ui.md

@@ -0,0 +1,44 @@
+# Fleet 控制台 UI（Phase A，dev.13）
+
+## 用户决策（2026-11-09）
+
+1. **配置保存必须即时生效**：不重启插件、不重启 DSH。→ Phase B 采用"运行时配置 + 持久化 overrides"设计（下一阶段实现）。
+2. 房间 UI 动作身份：以**用户**身份（ADR-0007）。
+3. 实施顺序：A → B → C → D。
+
+## 本阶段实现
+
+### Host 读模型
+
+`src/host/ui-web.js`：
+
+- `GET /device-fleet/overview`：`FleetNode.status()` + rooms 摘要 + approvals 列表；
+- `GET /device-fleet/rooms`：房间摘要列表；
+- `GET /device-fleet/rooms/:id`：房间详情（成员、策略、transcript、看板任务）。
+
+### Room 持久化 / rehydrate
+
+`RoomService` 新增 `stateFile`（`$DSH_HOME/device-fleet/rooms.json`）：
+
+- 每次 append（创建/成员/消息/任务/关闭）后原子写快照；
+- 启动时 `load()` 重建 rooms/members/messages/tasks；
+- 成员 agent 不序列化，唤醒时通过 `sessionController.resolveAgent(sessionId)` 懒解析；
+- 插件卸载不再关闭房间（避免重载即销毁）。
+
+**验证**：创建 room + worker-c + 任务 + 1 条消息 → 插件重载 → `room_status` 仍显示 2 名成员、1 条消息、1 个任务；`room_task_list` 保留任务。
+
+### Client
+
+`client.js` 新增：
+
+- `sidebar.panellist` 图标（id `fleet`，label `设备联邦`，圆形网格图标）；
+- `main` keyed 面板 `fleet` = Fleet 控制台，三个 Tab：
+  - **设备**：本机名称/id、直连地址、relay、发现数量；Fleet 成员列表（在线/离线）；回连地址；
+  - **房间**：房间列表（成员数/消息数/任务数），选中后展示成员、看板、时间线；
+  - **审批**：待审批列表 + 允许一次/15 分钟/拒绝（与快捷面板共用 Host API）。
+
+## 未完成（Phase B/C/D）
+
+- 配置页与即时生效（Phase B）；
+- 房间交互：以用户身份发消息、看板操作、邀请/移除成员（Phase C）；
+- 配对向导、设备操作、审批历史/授权撤销、SSE、通知、i18n、a11y（Phase C/D）。

package/docs/notes/ui-surface-audit.md

@@ -0,0 +1,93 @@
+# UI 呈现缺口审计（2026-11-09）
+
+## 现状盘点
+
+当前插件已实现的 UI 只有**审批面板**（dev.12）：
+
+- 入口：`sidebar.footer.action` 的「🛰️ 审批」；
+- 内容：`shell.overlay` 居中对话框，待审批列表 + 允许一次/15 分钟/拒绝；
+- 数据：Host `/device-fleet/approvals`、`/device-fleet/approvals/decide`。
+
+其余**全部**依靠模型工具文本输出或 profile YAML 配置，没有任何可视化：
+
+| 设计要素 | 当前呈现方式 | 缺口 |
+|---|---|---|
+| 设备列表 / 在线状态 / 直连地址 / relay / 发现 | `fleet_status` 文本 | 无设备页，无法看设备拓扑与连接路径 |
+| 配对：邀请码、加入、手动地址、设备移除 | `fleet_invite`/`fleet_join`/`fleet_connect` 工具 | 无配对向导，邀请码需在聊天里传 |
+| 插件配置（deviceName/direct/discovery/relay/execution/policy/approvals/prompt） | profile `cordis.patch.yml` | 完全无 UI，改配置要手改 YAML + 重启 |
+| Room 列表 / 房间状态 | `room_status`、`room_messages` 文本 | 无房间列表/视图 |
+| Room 成员（设备 × agent、host/local/remote） | `room_status` JSON | 无成员可视化，看不出"不同设备不同 agent" |
+| Room 时间线（用户可见完整对话） | `room_messages` 文本 | 无时间线 UI，无消息流式更新 |
+| Room 发消息 / 点名 | `room_send` 工具 | 无输入框/@成员操作 |
+| Room Board（任务、owner、状态、依赖、交接） | `room_task_*` 文本 | 无看板视图 |
+| 房间策略（invite/join/maxMembers/boardWrite） | 创建参数 | 无查看/编辑 |
+| 审批历史 / TTL 授权管理 | 收件箱列表（仅 pending） | 无历史、无授权撤销 |
+| 委派（fleet_delegate） | 工具结果文本 | 无历史/运行状态/中断入口 |
+| 直调审计（谁调了哪台设备什么工具） | 会话轨迹里 | 无 Fleet 维度审计页 |
+| 首次配对引导 | 无 | 新设备没有任何向导 |
+| 错误/诊断 | `fleet_status` + 日志 | 无连接诊断页 |
+| 通知 | 无 | 新审批/新消息没有系统通知 |
+| 国际化 | 中文硬编码 | 未接 Client locale 服务 |
+| 多窗口/实时 | 审批 2.5s 轮询 | Room/设备状态无推送，多窗口不同步 |
+
+## 关键基础设施缺口（UI 之前必须先补）
+
+1. **Host 读模型 API 不足**：目前只有 approvals 两条路由；需要
+   - `GET /device-fleet/overview`：本机身份/版本/直连/relay/discovery/roster/connected/peerHints；
+   - `GET /device-fleet/rooms`、`GET /device-fleet/rooms/:id`：成员、策略、transcript、tasks；
+   - `GET /device-fleet/events`（SSE）或长轮询：状态变化推送。
+2. **配置写路径缺失**：Cordis config 来自 profile patch，运行时不可写。需要确定：
+   - 方案 A（推荐）：`$DSH_HOME/device-fleet/config-overrides.json` + apply 时合并，UI 写该文件；保存后提示"重载插件生效"（或调用 Host 重新加载）；
+   - 方案 B：直接改写 profile `cordis.patch.yml`（风险高：破坏注释/结构，需备份）。
+3. **Room 状态无持久化/rehydrate**：RoomService 是内存 Map，插件重载/DSH 重启后房间消失。UI 之前应先做基于 host session 事件的 rehydrate，否则"房间视图"打开是空的。
+4. **UI 操作的身份与授权**：UI 里的"发消息/改任务/关房"是以**用户**身份还是 host agent 身份？需要 Room 服务暴露 user 动作并校验房主/成员权限。
+5. **Slot/设计系统**：已确认可用的官方扩展点：
+   - `sidebar.panellist`（全局面板图标）+ `main`（keyed 主面板）→ Fleet 控制台；
+   - `settings.section`（设置页）或 `plugins.bundle.config`（插件配置页，key = 包名）→ 配置 UI；
+   - `shell.overlay` → 对话框/房间详情；
+   - `sidebar.footer.action` → 快捷入口（审批已用）。
+6. **多设备语义呈现**：房间成员需要 "设备（名称/在线/连接路径）× agent（session/角色）" 两级标签；当前 member 只有 `local:session-…`/`host:…` 字符串，远程成员还没有实体，需要先接远程参与者传输。
+
+## 建议的信息架构
+
+```
+侧栏
+├─ 全局面板图标「Fleet」 (sidebar.panellist: id=fleet)
+│   └─ main keyed "fleet" 主面板
+│        ├─ 设备 Tab：本机状态、roster、在线/离线、直连/relay、配对按钮、诊断
+│        ├─ 房间 Tab：房间列表 → 房间详情（成员树、时间线、看板、策略）
+│        └─ 审批 Tab：待审批 + 历史 + 授权管理
+├─ Settings 上方「🛰️ 审批」快捷入口（已实现）
+└─ Settings → 插件 → Device Fleet 配置页
+     (plugins.bundle.config key "dsh-device-fleet" 或 plugins.row.config "dsh-device-fleet#device-fleet")
+     分块：设备/网络 · 执行上下文 · 远端权限(Tool Policy) · 本地审批 · 高级
+```
+
+## 分阶段实施计划
+
+**Phase A：Fleet 控制台（只读）**
+- Host `/overview`、`/rooms`、`/rooms/:id` API；
+- `sidebar.panellist` + `main` 主面板，三个 Tab：设备 / 房间 / 审批（待审批 + 只读时间线/看板）；
+- 先解决 Room rehydrate，否则只读视图无内容。
+
+**Phase B：配置 UI**
+- `plugins.bundle.config` 注册配置页；
+- 字段分组 + 校验 + 当前值显示；
+- 保存走 overrides 文件（方案 A），保存后提示重载插件；policy 的 roots/tools 用列表编辑器。
+
+**Phase C：交互动作**
+- 房间：以用户身份发消息（点名选择成员）、看板任务增改/交接、关房、邀请/移除成员（权限校验）；
+- 设备：配对向导（邀请码生成/扫码式复制、手动地址连接、移除设备）；
+- 审批：历史列表 + ttl 授权撤销。
+
+**Phase D：体验与可靠性**
+- SSE/事件推送替代轮询，多窗口同步；
+- 通知（新审批/新房间消息）；
+- Client locale（zh/en），a11y，空状态/引导；
+- 插件重载 rehydrate、房间日志持久补发（ADR-0018）。
+
+## 需要你确认的决策
+
+1. 配置写路径：选 **overrides 文件（推荐）** 还是直接改 profile YAML？
+2. 房间 UI 动作的身份：以 **用户** 身份（推荐，符合 ADR-0007 用户发言与设备解耦）还是 host agent 身份？
+3. 先做 Phase A（控制台只读）还是先做 Phase B（配置页）？我建议按 A → B → C → D。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-device-fleet",
-  "version": "0.1.0-dev.12",
+  "version": "0.1.0-dev.14",
   "description": "DeepSeek Harness device fleet: enroll devices, direct-call remote tools, shared Rooms with lazy-woken agents, and delegated subagents across devices.",
   "type": "module",
   "main": "src/plugin/index.js",

package/src/host/config-web.js

@@ -0,0 +1,61 @@
+// Runtime config HTTP surface (dev.14): read the effective config and apply a
+// patch live. The UI posts here; no plugin or DSH restart is involved.
+const MAX_BODY_BYTES = 256 * 1024
+
+function json(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(value))
+}
+
+async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > MAX_BODY_BYTES) throw Object.assign(new Error('request body is too large'), { code: 'body-too-large' })
+    chunks.push(chunk)
+  }
+  if (chunks.length === 0) return {}
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } catch {
+    throw Object.assign(new Error('request body must be JSON'), { code: 'bad-json' })
+  }
+}
+
+export function registerConfigRoutes({ webServer, runtime, logger = null }) {
+  if (!webServer?.register || !runtime) return () => {}
+  const disposers = []
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/config',
+      handler: async (req, res) => {
+        if (req.method === 'GET') {
+          try {
+            json(res, 200, runtime.snapshot())
+          } catch (error) {
+            json(res, 500, { error: String(error?.message ?? error) })
+          }
+          return
+        }
+        if (req.method !== 'POST') return json(res, 405, { error: 'method not allowed' })
+        try {
+          const body = await readJsonBody(req)
+          const patch = body?.patch ?? body
+          const config = await runtime.update(patch)
+          json(res, 200, { ok: true, config, appliedAt: Date.now() })
+        } catch (error) {
+          const status = ['bad-request', 'bad-json', 'body-too-large', 'readonly'].includes(error?.code) ? 400 : 500
+          if (status === 500) logger?.warn?.(`[device-fleet] config update failed: ${String(error?.message ?? error)}`)
+          json(res, status, { error: String(error?.message ?? error), code: error?.code ?? 'error' })
+        }
+      },
+    }),
+  )
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}

package/src/host/execution-slot.js

@@ -18,6 +18,14 @@ export class ExecutionSlot {
     this.initializing = null
   }
 
+  /** Replace the slot's creation config; the next call lazily recreates the agent. */
+  setConfig(next = {}) {
+    this.config = { ...this.config, ...(next ?? {}) }
+    this.agent = null
+    this.sessionId = null
+    this.initializing = null
+  }
+
   async ensureAgent() {
     if (this.agent) return this.agent
     if (this.initializing) return this.initializing

package/src/host/index.js

@@ -6,5 +6,8 @@ export * from './direct-call.js'
 export * from './delegation.js'
 export * from './approval-inbox.js'
 export * from './approval-web.js'
+export * from './ui-web.js'
+export * from './config-web.js'
+export * from './runtime-config.js'
 export * from './room-service.js'
 export * from './tools.js'

package/src/host/room-service.js

@@ -4,8 +4,11 @@
 // addressed message, so addressing/wake/visibility and board handoff can be
 // exercised before the remote transport and the client UI exist.
 import { randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
 
 const MAX_MESSAGE_CHARS = 20_000
+const STATE_VERSION = 1
 
 const DEFAULT_POLICY = Object.freeze({
   invite: 'members',
@@ -29,13 +32,85 @@ export class RoomService {
    * @param {object} options.sessionController ctx.sessionController
    * @param {(input: object) => object} [options.createUserMessage] dsh-llm helper
    * @param {(now?: number) => number} [options.now]
+   * @param {string} [options.stateFile] JSON file used to rehydrate rooms after a reload
    */
-  constructor({ sessionController, createUserMessage = null, now = Date.now } = {}) {
+  constructor({ sessionController, createUserMessage = null, now = Date.now, stateFile = null } = {}) {
     this.sessionController = sessionController
     this.createUserMessage = createUserMessage
     this.now = now
+    this.stateFile = stateFile
     /** @type {Map<string, any>} */
     this.rooms = new Map()
+    if (stateFile) this.load()
+  }
+
+  /** Rehydrate active rooms from the persisted snapshot (agents resolve lazily). */
+  load() {
+    if (!this.stateFile || !existsSync(this.stateFile)) return
+    try {
+      const data = JSON.parse(readFileSync(this.stateFile, 'utf8'))
+      if (!data || data.version !== STATE_VERSION || !Array.isArray(data.rooms)) return
+      for (const stored of data.rooms) {
+        if (!stored || typeof stored.roomId !== 'string' || !Array.isArray(stored.members)) continue
+        const members = new Map()
+        for (const member of stored.members) {
+          if (!member || typeof member.memberId !== 'string') continue
+          members.set(member.memberId, { ...member, agent: undefined })
+        }
+        if (!members.has(hostMemberId(stored.roomId))) continue
+        this.rooms.set(stored.roomId, {
+          roomId: stored.roomId,
+          createdAt: Number.isFinite(stored.createdAt) ? stored.createdAt : this.now(),
+          hostSessionId: typeof stored.hostSessionId === 'string' ? stored.hostSessionId : stored.roomId,
+          policy: { ...DEFAULT_POLICY, ...(stored.policy ?? {}) },
+          members,
+          messages: Array.isArray(stored.messages) ? stored.messages : [],
+          tasks: new Map((Array.isArray(stored.tasks) ? stored.tasks : []).map((task) => [task.id, task])),
+          closed: false,
+        })
+      }
+    } catch {
+      /* a corrupt snapshot is ignored; the host session log stays authoritative */
+    }
+  }
+
+  persist() {
+    if (!this.stateFile) return
+    try {
+      const snapshot = {
+        version: STATE_VERSION,
+        savedAt: this.now(),
+        rooms: [...this.rooms.values()].map((room) => ({
+          roomId: room.roomId,
+          createdAt: room.createdAt,
+          hostSessionId: room.hostSessionId,
+          policy: room.policy,
+          members: [...room.members.values()].map(({ agent, ...rest }) => rest),
+          messages: room.messages,
+          tasks: [...room.tasks.values()],
+        })),
+      }
+      mkdirSync(dirname(this.stateFile), { recursive: true })
+      const temporary = `${this.stateFile}.tmp`
+      writeFileSync(temporary, JSON.stringify(snapshot, null, 2), 'utf8')
+      renameSync(temporary, this.stateFile)
+    } catch {
+      /* persistence is best effort; the session log remains authoritative */
+    }
+  }
+
+  /** Resolve a live agent for a persisted member on demand. */
+  async ensureAgent(member) {
+    if (member?.agent) return true
+    if (!member?.sessionId || !this.sessionController?.resolveAgent) return false
+    try {
+      const resolved = await this.sessionController.resolveAgent(member.sessionId)
+      if (!resolved?.agent) return false
+      member.agent = resolved.agent
+      return true
+    } catch {
+      return false
+    }
   }
 
   async upgradeHost({ agent, policy = {} } = {}) {
@@ -169,7 +244,9 @@ export class RoomService {
 
   /** Wake one local participant by injecting the addressed message. */
   async wake(room, member, message) {
-    if (!member?.agent || typeof member.agent.followup !== 'function' || typeof this.createUserMessage !== 'function') return false
+    if (!member || typeof this.createUserMessage !== 'function') return false
+    if (!(await this.ensureAgent(member))) return false
+    if (typeof member.agent?.followup !== 'function') return false
     const senderLabel = message.from.kind === 'user' ? 'user' : (message.from.name ?? 'agent')
     const text = [
       `[Fleet Room ${room.roomId}] ${senderLabel} → you:`,
@@ -189,7 +266,14 @@ export class RoomService {
   async append(room, type, data) {
     const host = room.members.get(hostMemberId(room.hostSessionId))
     const session = host?.agent?.session
-    if (session?.append) await session.append(type, data)
+    if (session?.append) {
+      try {
+        await session.append(type, data)
+      } catch {
+        /* the snapshot below still records the room state */
+      }
+    }
+    this.persist()
   }
 
   // --------------------------------------------------------------- room tasks
@@ -303,6 +387,21 @@ export class RoomService {
     return this.summary(this.requireRoom(roomId))
   }
 
+  /** All active rooms (UI list). */
+  list() {
+    return [...this.rooms.values()].map((room) => this.summary(room))
+  }
+
+  /** One room plus its transcript and board (UI detail). */
+  detail(roomId, { limit = 100 } = {}) {
+    const room = this.requireRoom(roomId)
+    return {
+      ...this.summary(room),
+      messages: this.messages({ roomId, limit }),
+      tasks: this.listTasks(roomId),
+    }
+  }
+
   /** All open rooms (for cleanup and diagnostics). */
   openRooms() {
     return [...this.rooms.keys()]
@@ -313,6 +412,7 @@ export class RoomService {
     room.closed = true
     await this.append(room, 'room/closed', { roomId: room.roomId, reason, closedAt: this.now() })
     this.rooms.delete(room.roomId)
+    this.persist()
     return { roomId: room.roomId, closed: true, reason }
   }
 

package/src/host/runtime-config.js

@@ -0,0 +1,192 @@
+// Runtime configuration (ADR-0025): the profile patch stays the base layer,
+// while `$DSH_HOME/device-fleet/config-overrides.json` holds UI edits. Applying
+// a patch merges it, persists it and runs the registered live-apply handlers so
+// no plugin/DSH restart is required.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const READONLY_FIELDS = ['dataDir']
+const CAPABILITY_MODES = ['auto', 'ask', 'deny']
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function deepMerge(base, patch) {
+  if (!isPlainObject(patch)) return patch
+  const result = isPlainObject(base) ? { ...base } : {}
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue
+    if (Array.isArray(value)) result[key] = value.map((item) => (isPlainObject(item) ? deepMerge({}, item) : item))
+    else if (isPlainObject(value)) result[key] = deepMerge(result[key], value)
+    else result[key] = value
+  }
+  return result
+}
+
+function readJson(file) {
+  if (!file || !existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function requirePositiveInteger(value, name, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw Object.assign(new Error(`${name} must be an integer between ${min} and ${max}`), { code: 'bad-request' })
+  }
+  return value
+}
+
+function stringList(value, name) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw Object.assign(new Error(`${name} must be an array of strings`), { code: 'bad-request' })
+  }
+  return value.map((item) => item.trim()).filter((item) => item !== '')
+}
+
+function optionalString(value, name) {
+  if (value === undefined || value === null) return ''
+  if (typeof value !== 'string') throw Object.assign(new Error(`${name} must be a string`), { code: 'bad-request' })
+  return value.trim()
+}
+
+/**
+ * Validate and clean a UI patch. Only known fields survive; unknown keys are
+ * dropped instead of leaking arbitrary objects into the effective config.
+ */
+export function sanitizeConfigPatch(patch) {
+  if (!isPlainObject(patch)) throw Object.assign(new Error('config patch must be an object'), { code: 'bad-request' })
+  const clean = {}
+  if (patch.deviceName !== undefined) {
+    const name = optionalString(patch.deviceName, 'deviceName')
+    if (name !== '') clean.deviceName = name.slice(0, 80)
+  }
+  if (patch.promptSection !== undefined) clean.promptSection = patch.promptSection === true
+  if (patch.autoApproveAsk !== undefined) clean.autoApproveAsk = patch.autoApproveAsk === true
+  if (patch.discovery !== undefined) clean.discovery = patch.discovery === true
+  if (patch.dataDir !== undefined) {
+    throw Object.assign(new Error('dataDir cannot be changed at runtime'), { code: 'readonly' })
+  }
+  if (patch.direct !== undefined) {
+    if (!isPlainObject(patch.direct)) throw Object.assign(new Error('direct must be an object'), { code: 'bad-request' })
+    clean.direct = {
+      host: optionalString(patch.direct.host, 'direct.host') || '0.0.0.0',
+      port: requirePositiveInteger(Number(patch.direct.port ?? 0), 'direct.port', { min: 0, max: 65535 }),
+    }
+  }
+  if (patch.relay !== undefined) {
+    if (patch.relay === null) clean.relay = null
+    else if (isPlainObject(patch.relay)) {
+      clean.relay = {
+        host: optionalString(patch.relay.host, 'relay.host'),
+        port: requirePositiveInteger(Number(patch.relay.port ?? 0), 'relay.port', { min: 0, max: 65535 }),
+        dataPort: requirePositiveInteger(Number(patch.relay.dataPort ?? 0), 'relay.dataPort', { min: 0, max: 65535 }),
+        reconnect: patch.relay.reconnect !== false,
+      }
+      if (clean.relay.host === '' || clean.relay.port === 0) clean.relay = null
+    } else {
+      throw Object.assign(new Error('relay must be an object or null'), { code: 'bad-request' })
+    }
+  }
+  if (patch.execution !== undefined) {
+    if (!isPlainObject(patch.execution)) throw Object.assign(new Error('execution must be an object'), { code: 'bad-request' })
+    const execution = {}
+    if (patch.execution.cwd !== undefined) execution.cwd = optionalString(patch.execution.cwd, 'execution.cwd')
+    if (patch.execution.agentPreset !== undefined) execution.agentPreset = optionalString(patch.execution.agentPreset, 'execution.agentPreset')
+    if (patch.execution.shellTool !== undefined) execution.shellTool = optionalString(patch.execution.shellTool, 'execution.shellTool')
+    if (patch.execution.subagentProvider !== undefined) execution.subagentProvider = optionalString(patch.execution.subagentProvider, 'execution.subagentProvider')
+    if (patch.execution.approvalTimeoutMs !== undefined) {
+      execution.approvalTimeoutMs = requirePositiveInteger(Number(patch.execution.approvalTimeoutMs), 'execution.approvalTimeoutMs', { min: 1000 })
+    }
+    if (patch.execution.delegateTimeoutMs !== undefined) {
+      execution.delegateTimeoutMs = requirePositiveInteger(Number(patch.execution.delegateTimeoutMs), 'execution.delegateTimeoutMs', { min: 1000 })
+    }
+    clean.execution = execution
+  }
+  if (patch.policy !== undefined) {
+    if (!isPlainObject(patch.policy)) throw Object.assign(new Error('policy must be an object'), { code: 'bad-request' })
+    const policy = {}
+    if (patch.policy.allowedRoots !== undefined) policy.allowedRoots = stringList(patch.policy.allowedRoots, 'policy.allowedRoots')
+    if (patch.policy.allowedTools !== undefined) policy.allowedTools = stringList(patch.policy.allowedTools, 'policy.allowedTools')
+    if (patch.policy.approvalTtlMs !== undefined) {
+      policy.approvalTtlMs = requirePositiveInteger(Number(patch.policy.approvalTtlMs), 'policy.approvalTtlMs', { min: 1000 })
+    }
+    if (patch.policy.capabilities !== undefined) {
+      if (!isPlainObject(patch.policy.capabilities)) throw Object.assign(new Error('policy.capabilities must be an object'), { code: 'bad-request' })
+      const capabilities = {}
+      for (const [key, value] of Object.entries(patch.policy.capabilities)) {
+        if (!CAPABILITY_MODES.includes(value)) {
+          throw Object.assign(new Error(`policy.capabilities.${key} must be auto|ask|deny`), { code: 'bad-request' })
+        }
+        capabilities[key] = value
+      }
+      policy.capabilities = capabilities
+    }
+    clean.policy = policy
+  }
+  if (patch.approvals !== undefined) {
+    if (!isPlainObject(patch.approvals)) throw Object.assign(new Error('approvals must be an object'), { code: 'bad-request' })
+    const approvals = {}
+    if (patch.approvals.ttlMs !== undefined) approvals.ttlMs = requirePositiveInteger(Number(patch.approvals.ttlMs), 'approvals.ttlMs', { min: 1000 })
+    if (patch.approvals.maxPending !== undefined) approvals.maxPending = requirePositiveInteger(Number(patch.approvals.maxPending), 'approvals.maxPending', { min: 1 })
+    if (patch.approvals.simulation !== undefined) approvals.simulation = patch.approvals.simulation === true
+    clean.approvals = approvals
+  }
+  return clean
+}
+
+export class RuntimeConfig {
+  /**
+   * @param {object} options
+   * @param {object} options.base profile (Cordis) config
+   * @param {string} [options.overridesFile] JSON file edited from the UI
+   */
+  constructor({ base = {}, overridesFile = null } = {}) {
+    this.base = base
+    this.overridesFile = overridesFile
+    this.overrides = readJson(overridesFile) ?? {}
+    this.current = deepMerge(this.base, this.overrides)
+    this.applyHandlers = []
+    this.updating = Promise.resolve()
+  }
+
+  onChange(handler) {
+    this.applyHandlers.push(handler)
+  }
+
+  persist() {
+    if (!this.overridesFile) return
+    try {
+      mkdirSync(dirname(this.overridesFile), { recursive: true })
+      const temporary = `${this.overridesFile}.tmp`
+      writeFileSync(temporary, JSON.stringify(this.overrides, null, 2), 'utf8')
+      renameSync(temporary, this.overridesFile)
+    } catch {
+      /* overrides are best effort; the in-memory config is still applied */
+    }
+  }
+
+  /** Merge, persist and live-apply one patch. Returns the effective config. */
+  update(patch) {
+    const clean = sanitizeConfigPatch(patch)
+    return this.updating.then(async () => {
+      const previous = this.current
+      this.overrides = deepMerge(this.overrides, clean)
+      this.current = deepMerge(this.base, this.overrides)
+      this.persist()
+      for (const handler of this.applyHandlers) await handler(this.current, previous)
+      return this.current
+    })
+  }
+
+  snapshot() {
+    return {
+      config: this.current,
+      overrides: this.overrides,
+      readonly: READONLY_FIELDS,
+    }
+  }
+}