dsh-remote-agent 0.0.0-stage → 0.4.1

package/lib/pairing.js

@@ -0,0 +1,186 @@
+/**
+ * 配对码（pairing code）：把「副机要抄的连接信息」压缩成一行可粘贴的串。
+ *
+ * 解决的问题：小白部署时最容易抄错的就是 hubUrl / token 这两行 ——
+ * 少半个斜杠、token 尾部多个空格，表现都是"副机永远不上线"且无报错。
+ * 配对码让主机向导输出**一行** `dshra1://…`，副机配置里粘一个 `pair:` 字段
+ * 就完成连接配置（roots 仍然由副机自己声明 —— 它是副机的安全边界，
+ * 不能由主机侧的串决定）。
+ *
+ * 格式：`dshra1://` + base64url(JSON)。选择理由：
+ *   - base64url 字符集（A-Za-z0-9_-）不含 YAML/JSON 特殊字符，粘贴安全；
+ *   - 带 `://` 看起来像一个链接，用户知道"这是一整段，别抄一半"；
+ *   - 版本号 v 在载荷里，未来改格式能平滑识别旧码。
+ *
+ * 安全注意：**配对码里含 token，等同凭证**。文档要求只通过可信渠道
+ * （当面/加密聊天）传给副机，不要贴公开群里。
+ *
+ * 纯函数、零依赖、永不抛 —— 解析失败一律返回结构化错误，让人话修法
+ * 能一路带到向导 / doctor / worker 日志三个出口。
+ */
+
+export const PAIR_SCHEME = 'dshra1://'
+/** 配对码长度上限：正常载荷 <300 字符，上限只防病态粘贴。 */
+const MAX_PAIR_LENGTH = 4096
+/** 载荷里允许出现的字段（多余字段忽略，防止未来字段变成注入面）。 */
+const PAYLOAD_KEYS = ['v', 'transportMode', 'hubUrl', 'relayUrl', 'token', 'nodeId', 'hubFingerprint']
+/**
+ * hub 指纹（P2-11）。与 lib/identity.js 的 normalizeFingerprint 同形 ——
+ * 刻意不 import：pairing 必须保持零 Node 内置模块依赖（client 的 web 包
+ * 也走这里，identity.js 里的 fs/child_process 进不了浏览器）。两处改一处必同步。
+ */
+const HUB_FINGERPRINT_RE = /^hubfp1-[A-Za-z0-9_-]{22}$/
+/** 与 protocol.validateHello / lib/setup.js NODE_ID_RE 一致。 */
+const NODE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+
+function isPlainObject(v) {
+  return Boolean(v) && typeof v === 'object' && !Array.isArray(v)
+}
+
+function cleanStr(v) {
+  return typeof v === 'string' ? v.trim() : ''
+}
+
+/**
+ * 生成配对码。输入任意垃圾字段都安全（非法值直接不放进载荷）。
+ * @param {object} o
+ * @param {string} [o.hubUrl] direct 模式拨入地址（与 relayUrl 至少给一个）
+ * @param {string} [o.relayUrl] relay 模式会合地址
+ * @param {string} [o.token] 入网 token（可空 —— 仅限可信内网）
+ * @param {string} [o.nodeId] 建议副机使用的节点 id
+ * @returns {string} `dshra1://...`；输入不足（连地址都没有）时返回 ''
+ */
+export function encodePairCode({ hubUrl = '', relayUrl = '', token = '', nodeId = '', hubFingerprint = '' } = {}) {
+  const payload = { v: 1 }
+  const mode = relayUrl && !hubUrl ? 'relay' : 'direct'
+  if (mode === 'relay' && cleanStr(relayUrl) !== '') {
+    payload.transportMode = 'relay'
+    payload.relayUrl = cleanStr(relayUrl)
+  } else if (cleanStr(hubUrl) !== '') {
+    payload.hubUrl = cleanStr(hubUrl)
+  } else {
+    return '' // 没有任何地址，无法构成有效配对码
+  }
+  if (cleanStr(token) !== '') payload.token = cleanStr(token)
+  if (cleanStr(nodeId) !== '' && NODE_ID_RE.test(cleanStr(nodeId))) payload.nodeId = cleanStr(nodeId)
+  // hub 指纹（P2-11）：副机展开配对码时自动变成 pinnedHubFingerprint（TOFU 钉住）。
+  // 形态不对就整个不放进去 —— 载荷里永远只有合法字段。
+  if (cleanStr(hubFingerprint) !== '' && HUB_FINGERPRINT_RE.test(cleanStr(hubFingerprint))) {
+    payload.hubFingerprint = cleanStr(hubFingerprint)
+  }
+  const json = JSON.stringify(payload)
+  return PAIR_SCHEME + Buffer.from(json, 'utf8').toString('base64url')
+}
+
+/**
+ * 解析配对码。容错：首尾空白、中间换行（终端复制常见）、成对引号。
+ * @returns {{ok:true, payload:object}|{ok:false, error:string}}
+ *   error 是给人看的中文（向导 / doctor 直接展示）。
+ */
+export function decodePairCode(raw) {
+  let s = cleanStr(raw)
+  if (s === '') return { ok: false, error: '配对码为空 —— 请把主机向导输出的 dshra1:// 整行完整粘贴进来' }
+  // 去掉粘贴时裹上的成对引号（YAML/聊天软件常见）
+  if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"'))) {
+    s = s.slice(1, -1).trim()
+  }
+  // 中间的换行/制表是"复制时被折行"的典型形态，拼接回来
+  s = s.replace(/[\r\n\t]+/g, '')
+  if (s.length > MAX_PAIR_LENGTH) {
+    return { ok: false, error: `配对码过长（>${MAX_PAIR_LENGTH} 字符）—— 疑似粘错了内容，请重新复制主机输出的 dshra1:// 整行` }
+  }
+  if (!s.toLowerCase().startsWith(PAIR_SCHEME)) {
+    return { ok: false, error: `不是配对码 —— 配对码以 ${PAIR_SCHEME} 开头（地址请填在 hubUrl 字段，两者别混）` }
+  }
+  const b64 = s.slice(PAIR_SCHEME.length)
+  if (b64 === '' || !/^[A-Za-z0-9_-]+$/.test(b64)) {
+    return { ok: false, error: '配对码内容不完整 —— 只含字母数字和 - _ 才是合法的 dshra1 码，请从主机重新完整复制' }
+  }
+  let payload
+  try {
+    payload = JSON.parse(Buffer.from(b64, 'base64url').toString('utf8'))
+  } catch {
+    return { ok: false, error: '配对码解析不了（内容被截断或改过）—— 请回主机向导重新生成，整行复制' }
+  }
+  if (!isPlainObject(payload)) {
+    return { ok: false, error: '配对码内容不是有效的 dshra1 载荷 —— 请回主机向导重新生成' }
+  }
+  if (payload.v !== 1) {
+    return { ok: false, error: `配对码版本不受支持（v=${payload.v}）—— 请把两边的 dsh-remote-agent 都升级到同一版本` }
+  }
+  // 只保留白名单字段（ignore 未来新增字段，保证旧版本可读性）
+  const clean = {}
+  for (const k of PAYLOAD_KEYS) {
+    if (payload[k] !== undefined) clean[k] = payload[k]
+  }
+  const mode = clean.transportMode === 'relay' ? 'relay' : 'direct'
+  if (mode === 'relay') {
+    if (cleanStr(clean.relayUrl) === '') {
+      return { ok: false, error: '配对码是 relay 模式但缺 relayUrl —— 请回主机向导重新生成' }
+    }
+    clean.transportMode = 'relay'
+    clean.hubUrl = undefined
+  } else {
+    if (cleanStr(clean.hubUrl) === '') {
+      return { ok: false, error: '配对码里没有主机地址 —— 请回主机向导重新生成' }
+    }
+    clean.transportMode = undefined
+    clean.relayUrl = undefined
+  }
+  if (clean.token !== undefined && typeof clean.token !== 'string') {
+    return { ok: false, error: '配对码里的 token 字段损坏 —— 请回主机向导重新生成' }
+  }
+  if (clean.nodeId !== undefined && (typeof clean.nodeId !== 'string' || !NODE_ID_RE.test(clean.nodeId))) {
+    return { ok: false, error: '配对码里的 nodeId 不合法 —— 请回主机向导重新生成' }
+  }
+  if (clean.hubFingerprint !== undefined) {
+    if (typeof clean.hubFingerprint !== 'string' || !HUB_FINGERPRINT_RE.test(clean.hubFingerprint.trim())) {
+      return { ok: false, error: '配对码里的 hubFingerprint 不合法 —— 请回主机向导重新生成' }
+    }
+    clean.hubFingerprint = clean.hubFingerprint.trim()
+  }
+  // undefined 字段不进最终载荷（JSON.stringify 会丢，这里手动保持一致）
+  for (const k of Object.keys(clean)) {
+    if (clean[k] === undefined) delete clean[k]
+  }
+  return { ok: true, payload: clean }
+}
+
+/**
+ * 把配置里的 `pair` 字段展开成具体的连接字段。
+ *
+ * 规则：
+ *   - **显式配置优先** —— 用户手写了 hubUrl/token/nodeId 就不覆盖（配对码
+ *     只是"默认值包"，不是强覆盖；方便临时换地址调试）。
+ *   - 展开成功后从结果里删掉 `pair` 键（避免 token 在配置对象里存两份）。
+ *   - **永不抛**：pair 缺失/无效时原样返回 config 并给出 error，让调用方
+ *     （worker 启动路径）只降级不炸。
+ *
+ * @param {object} config worker 的原始 config（容错：null/undefined 均可）
+ * @returns {{config:object, error:string}} error 为 '' 表示展开成功或本无 pair
+ */
+export function expandPairConfig(config) {
+  const src = isPlainObject(config) ? config : {}
+  const pairRaw = cleanStr(src.pair)
+  if (pairRaw === '') return { config: { ...src }, error: '' }
+  const dec = decodePairCode(pairRaw)
+  if (!dec.ok) return { config: { ...src }, error: dec.error }
+  const p = dec.payload
+  const out = { ...src }
+  delete out.pair
+  const fill = (key, value) => {
+    if (value !== undefined && cleanStr(out[key]) === '') out[key] = value
+  }
+  if (p.transportMode === 'relay') {
+    out.transportMode = out.transportMode === 'relay' ? out.transportMode : (cleanStr(out.transportMode) === '' ? 'relay' : out.transportMode)
+    fill('relayUrl', p.relayUrl)
+  } else {
+    fill('transportMode', 'direct')
+    fill('hubUrl', p.hubUrl)
+  }
+  fill('token', p.token)
+  fill('nodeId', p.nodeId)
+  // P2-11：指纹随码分发 → 副机零终端完成"连接配置 + hub 身份钉住"两件事。
+  fill('pinnedHubFingerprint', p.hubFingerprint)
+  return { config: out, error: '' }
+}

package/lib/protocol.js

@@ -0,0 +1,414 @@
+/**
+ * dsh-remote-agent 协议层（零外部依赖）。
+ *
+ * 设计要点：
+ *  - 单向凭证：模型 key / 会话日志 / 插件只存在于各自机器，协议里永远不出现模型凭证。
+ *  - 任务幂等：taskId 由 hub 生成，node 按 id 去重，重连重发不重复执行。
+ *  - 清单先于字节：产物先回 manifest，hub 显式 pull 才传输字节。
+ *  - 版本协商：hello/welcome 里带 protocol，不匹配时 node 主动拒绝而不是半懂半不懂地跑。
+ */
+
+export const PROTOCOL_VERSION = 1
+
+/** 帧类型。hub→node 与 node→hub 分列，避免拼写漂移。 */
+export const HUB_TO_NODE = Object.freeze({
+  WELCOME: 'welcome',
+  /**
+   * hub 身份帧（P2-11）。direct 模式的身份证明放在 welcome 里；relay 模式
+   * 副机的"在线"信号来自中继的 accepted，hub 在握手期对副机静默，只能
+   * 在节点上线后**追发**这一帧补上身份证明。副机未验证通过前拒绝执行任务。
+   */
+  IDENTITY: 'hub/identity',
+  /**
+   * E2E 密钥交换确认（提案 #1）：hub 对副机的 node/e2e 提议的签名回应。
+   * 载荷 { pub, sig, at } —— pub 是 hub 的 X25519 临时公钥，sig 用 hub 持久
+   * ed25519 身份签出（绑定双方公钥 + 连接 nonce）。中继只转发，无法伪造。
+   */
+  E2E_ACK: 'hub/e2e',
+  TASK_START: 'task/start',
+  TASK_CANCEL: 'task/cancel',
+  TASK_QUERY: 'task/query',
+  ARTIFACT_LIST: 'artifact/list',
+  ARTIFACT_PULL: 'artifact/pull',
+  ARTIFACT_CANCEL: 'artifact/cancel',
+  PING: 'ping',
+  ERROR: 'error',
+})
+
+export const NODE_TO_HUB = Object.freeze({
+  HELLO: 'hello',
+  /** 重连后主动上报本机全部任务状态 —— 任务状态的真身在副机，不在 hub。 */
+  TASK_SYNC: 'task/sync',
+  TASK_ACCEPT: 'task/accept',
+  TASK_PROGRESS: 'task/progress',
+  TASK_SUMMARY: 'task/summary',
+  TASK_END: 'task/end',
+  ARTIFACT_MANIFEST: 'artifact/manifest',
+  ARTIFACT_CHUNK: 'artifact/chunk',
+  ARTIFACT_DONE: 'artifact/done',
+  /** 资源遥测（CPU/内存/负载，~30s 一次）：派发前先看节点负载。尽力而为，字段可缺。 */
+  RESOURCE: 'node/resource',
+  /**
+   * 仓库清单上报（提案 #13）：副机把 roots 下扫到的 git 仓库（名字/远端
+   * url/本机路径）报给 hub，hub 建 repo→node 索引供 remote_task 的 repo:
+   * 参数路由。接入后与每 10min 各发一次；尽力而为，旧 hub 会按未知帧忽略。
+   */
+  REPOS: 'node/repos',
+  /**
+   * E2E 密钥交换提议（提案 #1）：副机上线后发一次，载荷 { pub, nonce } ——
+   * pub 是副机的一次性 X25519 公钥。hub 用持久身份签名确认（hub/e2e）。
+   * 旧 hub 按未知帧忽略 → 协商不成就继续明文（混跑安全）。
+   */
+  E2E_OFFER: 'node/e2e',
+  PONG: 'pong',
+  ERROR: 'error',
+})
+
+/** 中继层信封（relay 只做寻址与转发，不理解业务帧）。 */
+export const RELAY_FRAME = Object.freeze({
+  UP: 'up', // node → relay → hub
+  DOWN: 'down', // hub → relay → node
+  NODE_ONLINE: 'node/online',
+  NODE_OFFLINE: 'node/offline',
+  NODE_LIST: 'node/list',
+  HELLO_NODE: 'hello/node',
+  HELLO_HUB: 'hello/hub',
+  // 中继级错误（鉴权失败、nodeId 冲突、目标离线、被吊销）。
+  // 早期版本漏定义此常量，而 relay.js 有 8 处 sendJson(conn, RELAY_FRAME.ERROR, ...)：
+  // t 为 undefined → JSON.stringify 丢弃该字段 → 对端 decodeFrame 报 missing-type，
+  // 于是**所有中继错误帧都送不到**，transport.js / node-registry.js 的 ERROR 分支
+  // 也因 `frame.t === undefined` 永假而永不触发。
+  ERROR: 'error',
+})
+
+export const TASK_STATUS = Object.freeze({
+  QUEUED: 'queued',
+  /** 两阶段审批（提案 #2）：hub 已受理但**尚未派给副机**，等面板批准。 */
+  PENDING_APPROVAL: 'pending_approval',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  ABORTED: 'aborted',
+  INTERRUPTED: 'interrupted',
+  /** 两阶段审批终态：面板拒绝 / 审批超时 / 挂起期间被取消。 */
+  REJECTED: 'rejected',
+})
+
+export const TERMINAL_STATUS = new Set([
+  TASK_STATUS.COMPLETED,
+  TASK_STATUS.FAILED,
+  TASK_STATUS.ABORTED,
+  TASK_STATUS.INTERRUPTED,
+  TASK_STATUS.REJECTED,
+])
+
+export const TASK_MODE = Object.freeze({
+  /** 副机本机起一个真实 DSH agent 会话，独立模型上下文，任务在副机持久运行。 */
+  AGENT: 'agent',
+  /** 副机直接执行一段命令（调试 / 简单活）。 */
+  EXEC: 'exec',
+})
+
+export const ARTIFACT_ROLE = Object.freeze({
+  /** 成品：允许 hub 显式 pull。 */
+  FINAL: 'final',
+  /** 中间产物：只在副机留存，仅上报元数据。 */
+  INTERMEDIATE: 'intermediate',
+  /** 未归类：上报元数据，默认不可 pull。 */
+  OTHER: 'other',
+})
+
+export const ARTIFACT_KIND = Object.freeze({
+  FILE: 'file',
+  DIR: 'dir',
+  DIFF: 'diff',
+  REPORT: 'report',
+  MEDIA: 'media',
+})
+
+export const ERROR_CODE = Object.freeze({
+  PROTOCOL_MISMATCH: 'protocol-mismatch',
+  UNAUTHORIZED: 'unauthorized',
+  DUPLICATE_NODE: 'duplicate-node',
+  TASK_DUPLICATE: 'task-duplicate',
+  TASK_UNKNOWN: 'task-unknown',
+  WORKSPACE_DENIED: 'workspace-denied',
+  ARTIFACT_DENIED: 'artifact-denied',
+  ARTIFACT_MISSING: 'artifact-missing',
+  ARTIFACT_TOO_LARGE: 'artifact-too-large',
+  HASH_MISMATCH: 'hash-mismatch',
+  /** hub 身份验证失败：指纹不匹配 / 签名无效 / nonce 对不上 / 时间戳超窗。 */
+  HUB_IDENTITY_MISMATCH: 'hub-identity-mismatch',
+  /** relay 模式下 hub 身份帧尚未到达（宽限窗口内），任务暂不执行。 */
+  HUB_IDENTITY_PENDING: 'hub-identity-pending',
+  /**
+   * E2E 会话丢失（提案 #1）：hub 侧没有该节点的会话（典型：hub 重启而中继
+   * 与副机的连接还活着）。副机收到后重新走 node/e2e 握手。必须走明文 ERROR
+   * 帧 —— 此时双方已无共享密钥可言。
+   */
+  E2E_RESET: 'e2e-reset',
+  /** 副机侧拒绝未加密的业务帧（会话已建立却收到明文 = 伪造或 hub 丢会话）。 */
+  E2E_REQUIRED: 'e2e-required',
+  INTERNAL: 'internal',
+})
+
+export const DEFAULT_HEARTBEAT_MS = 15_000
+export const DEFAULT_ACK_TIMEOUT_MS = 60_000
+export const DEFAULT_PULL_TIMEOUT_MS = 30 * 60 * 1000
+/** 单帧二进制分块上限：256 KiB（base64 回退时约 341 KiB）。 */
+export const ARTIFACT_CHUNK_BYTES = 256 * 1024
+/** 中继/控制帧的单帧文本上限，防止畸形帧吃内存。 */
+export const MAX_CONTROL_FRAME_BYTES = 4 * 1024 * 1024
+export const MAX_ARTIFACT_FRAME_BYTES = 8 * 1024 * 1024
+
+let counter = 0
+
+/** 生成一个短小、无依赖、可读的 id。 */
+export function newId(prefix = 'x') {
+  counter = (counter + 1) & 0xffffff
+  const t = Date.now().toString(36)
+  const r = Math.floor(Math.random() * 0x10000).toString(36)
+  return `${prefix}-${t}${r}${counter.toString(36)}`
+}
+
+export function newTaskId() {
+  return newId('t')
+}
+
+export function newPullId() {
+  return newId('p')
+}
+
+/** 构造一个协议信封。 */
+export function envelope(type, data, opts = {}) {
+  const frame = { v: PROTOCOL_VERSION, t: type, id: opts.id ?? newId('m'), d: data ?? {} }
+  if (opts.replyTo) frame.r = opts.replyTo
+  return frame
+}
+
+export function encodeFrame(frame) {
+  return JSON.stringify(frame)
+}
+
+/**
+ * 二进制帧：`[u16 BE 头部长度][头部 JSON][净荷字节]`。
+ *
+ * 为什么不用 base64 塞进 JSON：产物分块是纯字节流，base64 有 33% 膨胀，
+ * 而且中继必须能只读头部就完成路由 —— 净荷一个字节都不该被解码。
+ */
+export function encodeBinaryFrame(header, payload) {
+  const head = Buffer.from(JSON.stringify(header), 'utf8')
+  if (head.length > 0xffff) throw new RemoteAgentError('binary frame header too large', ERROR_CODE.INTERNAL)
+  const out = Buffer.allocUnsafe(2 + head.length + payload.length)
+  out.writeUInt16BE(head.length, 0)
+  head.copy(out, 2)
+  payload.copy(out, 2 + head.length)
+  return out
+}
+
+/** 解析二进制帧。失败返回 {ok:false}，绝不抛。 */
+export function decodeBinaryFrame(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 2) return { ok: false, error: 'binary-frame-too-short' }
+  const headLen = buf.readUInt16BE(0)
+  if (buf.length < 2 + headLen) return { ok: false, error: 'binary-frame-header-truncated' }
+  let header
+  try {
+    header = JSON.parse(buf.subarray(2, 2 + headLen).toString('utf8'))
+  } catch {
+    return { ok: false, error: 'binary-frame-header-malformed' }
+  }
+  if (!header || typeof header !== 'object') return { ok: false, error: 'binary-frame-header-not-object' }
+  return { ok: true, header, payload: buf.subarray(2 + headLen) }
+}
+
+/**
+ * 把二进制编解码器注入传输层，避免 ws.js ↔ transport.js 的模块初始化期循环依赖。
+ * 在 node/transport.js 加载时自动完成；单独使用 protocol.js 时不需要调用。
+ */
+export function bindBinaryCodecInto(transportModule) {
+  transportModule.bindBinaryCodec(encodeBinaryFrame, decodeBinaryFrame)
+}
+
+/**
+ * 解析并校验一个信封。
+ * @returns {{ok:true, frame:object} | {ok:false, error:string}}
+ */
+export function decodeFrame(raw) {
+  let parsed
+  try {
+    parsed = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf8'))
+  } catch {
+    return { ok: false, error: 'malformed-json' }
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { ok: false, error: 'malformed-envelope' }
+  }
+  if (typeof parsed.t !== 'string' || parsed.t === '') {
+    return { ok: false, error: 'missing-type' }
+  }
+  if (parsed.v !== PROTOCOL_VERSION) {
+    return { ok: false, error: ERROR_CODE.PROTOCOL_MISMATCH }
+  }
+  return { ok: true, frame: parsed }
+}
+
+/** 一个协议错误，携带稳定 code，便于上层映射到工具错误。 */
+export class RemoteAgentError extends Error {
+  constructor(message, code = ERROR_CODE.INTERNAL, details = undefined) {
+    super(message)
+    this.name = 'RemoteAgentError'
+    this.code = code
+    this.details = details
+  }
+}
+
+/**
+ * 校验 hello 帧。node 与 hub 共用，保证双方对"什么是合法节点"理解一致。
+ * @returns {{ok:true, hello:object} | {ok:false, error:string}}
+ */
+export function validateHello(d) {
+  if (!d || typeof d !== 'object') return { ok: false, error: 'hello-missing' }
+  if (typeof d.nodeId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(d.nodeId)) {
+    return { ok: false, error: 'hello-nodeId-invalid' }
+  }
+  if (d.protocol !== PROTOCOL_VERSION) {
+    return { ok: false, error: ERROR_CODE.PROTOCOL_MISMATCH }
+  }
+  const os = d.os === 'windows' || d.os === 'linux' || d.os === 'darwin' ? d.os : undefined
+  if (!os) return { ok: false, error: 'hello-os-invalid' }
+  return {
+    ok: true,
+    hello: {
+      nodeId: d.nodeId,
+      protocol: d.protocol,
+      os,
+      arch: typeof d.arch === 'string' ? d.arch : 'unknown',
+      hostname: typeof d.hostname === 'string' ? d.hostname : d.nodeId,
+      dshVersion: typeof d.dshVersion === 'string' ? d.dshVersion : '',
+      shells: Array.isArray(d.shells) ? d.shells.filter((s) => typeof s === 'string') : [],
+      roots: Array.isArray(d.roots) ? d.roots.filter((s) => typeof s === 'string') : [],
+      caps: Array.isArray(d.caps) ? d.caps.filter((s) => typeof s === 'string') : [],
+      profile: typeof d.profile === 'string' ? d.profile : '',
+      agentMode: d.agentMode === true,
+      // P2-11：本次连接的挑战随机数（hex）。hub 把它签进 welcome/hub-identity
+      // 的身份证明，副机核对一致 —— 防"录一帧旧 welcome 重放给新连接"。
+      // 缺失（旧版副机）时为空串，hub 退化成自拟 nonce + 时间戳窗口。
+      nonce: typeof d.nonce === 'string' && /^[0-9a-f]{16,128}$/.test(d.nonce) ? d.nonce : '',
+      time: typeof d.time === 'number' ? d.time : Date.now(),
+    },
+  }
+}
+
+/**
+ * 归一化 `artifactRules`，**含内层形状校验**。
+ *
+ * 合法形状：`{ final?: string[], intermediate?: string[], caseInsensitive?: boolean }`
+ * （见 lib/artifacts.js 的 `classify()` —— 它读 `rules.intermediate?.length` /
+ * `rules.final?.length` 后交给 `compileRules`，后者要求数组）。
+ *
+ * 为什么必须校验内层：`typeof x === 'object'` 只挡住 null/undefined/数字/布尔，
+ * **字符串与数组也能通过**。而 `'dist/**'.length` 是真值，于是：
+ *   - 传 `{ final: 'dist/**' }` → `rules.final?.length` 为 7（真）→
+ *     `compileRules('dist/**')` 把字符串按可迭代对象处理 → 逐字符编译成规则，
+ *     得到 `["d","i","s","t","/","*","*"]` 这类垃圾。
+ *   - 实测后果：单字符文件被误判为可 pull 的 final，而真正的 `dist/app.js`
+ *     反而漏掉，**无异常、无日志**。
+ *
+ * 非数组一律丢弃（与 outputs / denyPaths 的处理方式一致），而不是静默透传。
+ * `caseInsensitive` 只接受真正的布尔。
+ */
+export function normalizeArtifactRules(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  const pick = (v) => (Array.isArray(v) ? v.filter((p) => typeof p === 'string' && p !== '') : undefined)
+  const out = {}
+  const final = pick(raw.final)
+  const intermediate = pick(raw.intermediate)
+  if (final !== undefined) out.final = final
+  if (intermediate !== undefined) out.intermediate = intermediate
+  if (typeof raw.caseInsensitive === 'boolean') out.caseInsensitive = raw.caseInsensitive
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * 归一化一个模型选择（可选）。
+ *
+ * 接受三种写法（对小白最友好到最精确）：
+ *   - `'gpt-4o'`                  → `{ model: 'gpt-4o' }`（provider 用副机默认）
+ *   - `'openai/gpt-4o'`           → `{ provider: 'openai', model: 'gpt-4o' }`
+ *   - `{ provider, model, reasoningEffort? }` → 逐字段过滤后原样保留
+ *
+ * 其他输入（数字 / 数组 / 空串 / 字段类型不对）一律返回 undefined，
+ * 与 outputs / denyPaths 的处理方式一致 —— 宁可丢掉一个坏参数回到
+ * "副机默认模型"，也不能把垃圾透传给 runner。
+ *
+ * 注意：这里只传**选择**，不传凭证 —— 模型 key 始终在副机（核心不变式 1）。
+ * 副机拿到选择后用自己的 provider 配置去跑；指定的 provider/model 在副机
+ * 不存在时，错误会经 agent/error 监听如实进入 handoff（2026-10-15 修复后
+ * 错误不再被静默吞掉）。
+ */
+export function normalizeModelSelection(raw) {
+  if (raw === undefined || raw === null) return undefined
+
+  if (typeof raw === 'string') {
+    const s = raw.trim()
+    if (s === '') return undefined
+    // 'provider/model'：provider 段不含 '/'，model 段允许再带（如 openrouter 的 org/model）
+    const slash = s.indexOf('/')
+    if (slash > 0 && slash < s.length - 1) {
+      return { provider: s.slice(0, slash).slice(0, 64), model: s.slice(slash + 1).slice(0, 128) }
+    }
+    return { model: s.slice(0, 128) }
+  }
+
+  if (typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  const out = {}
+  if (typeof raw.provider === 'string' && raw.provider !== '') out.provider = raw.provider.slice(0, 64)
+  if (typeof raw.model === 'string' && raw.model !== '') out.model = raw.model.slice(0, 128)
+  if (typeof raw.reasoningEffort === 'string' && raw.reasoningEffort !== '') {
+    out.reasoningEffort = raw.reasoningEffort.slice(0, 32)
+  }
+  // 没有 model 的选择不是合法选择（provider 必须配 model，单独 provider 无效）——
+  // 与 outputs / denyPaths 一致：坏参数丢掉，回到副机默认。
+  if (out.model === undefined) return undefined
+  return out
+}
+
+/**
+ * 校验 task/start 帧。
+ * @returns {{ok:true, spec:object} | {ok:false, error:string}}
+ */
+export function validateTaskStart(d) {
+  if (!d || typeof d !== 'object') return { ok: false, error: 'task-missing' }
+  if (typeof d.taskId !== 'string' || d.taskId === '') return { ok: false, error: 'task-taskId-missing' }
+  if (typeof d.goal !== 'string' || d.goal.trim() === '') return { ok: false, error: 'task-goal-missing' }
+  const mode = d.mode === TASK_MODE.EXEC ? TASK_MODE.EXEC : TASK_MODE.AGENT
+  const c = d.constraints && typeof d.constraints === 'object' ? d.constraints : {}
+  return {
+    ok: true,
+    spec: {
+      taskId: d.taskId,
+      goal: d.goal,
+      workspace: typeof d.workspace === 'string' && d.workspace ? d.workspace : undefined,
+      mode,
+      model: normalizeModelSelection(d.model),
+      constraints: {
+        timeoutMs: Number.isFinite(c.timeoutMs) ? Math.max(1000, c.timeoutMs) : 60 * 60 * 1000,
+        maxBytesWritten: Number.isFinite(c.maxBytesWritten) ? c.maxBytesWritten : 2 * 1024 * 1024 * 1024,
+        allowNetwork: c.allowNetwork !== false,
+        denyPaths: Array.isArray(c.denyPaths) ? c.denyPaths.filter((p) => typeof p === 'string') : [],
+        extraEnv: c.extraEnv && typeof c.extraEnv === 'object' ? c.extraEnv : {},
+      },
+      outputs: Array.isArray(d.outputs) ? d.outputs.filter((p) => typeof p === 'string') : [],
+      // 两阶段审批（提案 #2）：'manual' = hub 挂起待面板批准；缺省时 exec
+      // 任务默认 manual（保守默认，显式传 'auto' 退回旧行为），agent 任务
+      // 默认 auto（agent 会话本身就是交互式的，再卡一道审批只会添堵）。
+      approval: d.approval === 'manual' || d.approval === 'auto'
+        ? d.approval
+        : (mode === TASK_MODE.EXEC ? 'manual' : 'auto'),
+      artifactRules: normalizeArtifactRules(d.artifactRules),
+      summaryPolicy: d.summaryPolicy === 'stream' ? 'stream' : 'on-complete',
+      requestedAt: typeof d.requestedAt === 'number' ? d.requestedAt : Date.now(),
+      origin: typeof d.origin === 'string' ? d.origin : 'hub',
+    },
+  }
+}