dsh-punky-swarm 0.3.6

package/lib/discovery/schema.js

@@ -0,0 +1,157 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// 发现协议（ADP，Agent Discovery Protocol）常量与请求校验 — 独立模块，核心无感知。
+// 基准：ACPs-community v2.1.0（acps-sdk/adp + discovery-server/app/discovery，06-ACPs-spec-ADP）。
+// 字段名以参考实现逐字为准（lowerCamelCase），不臆造。纯函数 + 数据，零运行时依赖。
+
+// ── 查询类型（QUERY_TYPES，与 acps_sdk/adp/constants.py 一致）──
+export const QUERY_TYPES = ['explicit', 'exploratory', 'trending', 'filtered'];
+export const QUERY_TYPE_EXPLICIT = 'explicit';
+
+// ── 转发限制（FORWARD_*，与 acps_sdk/adp/constants.py 一致）──
+export const FORWARD_DEPTH_LIMIT_DEFAULT = 3;   // 服务器默认
+export const FORWARD_DEPTH_LIMIT_MIN = 1;
+export const FORWARD_DEPTH_LIMIT_MAX = 5;       // 绝对上限
+export const FORWARD_FANOUT_LIMIT_DEFAULT = 1;  // 未提供时默认不允许并发转发
+export const FORWARD_FANOUT_LIMIT_MIN = 1;
+export const FORWARD_FANOUT_LIMIT_MAX = 5;
+export const FORWARD_EACH_TIMEOUT_MS_DEFAULT = 10_000;
+export const FORWARD_TOTAL_TIMEOUT_MS_DEFAULT = 60_000;
+
+// ── 查询结果限制（服务器默认 5，上限 50，同 discovery-server/schema.py）──
+export const DISCOVERY_LIMIT_DEFAULT = 5;
+export const DISCOVERY_LIMIT_MAX = 50;
+
+// ── 过滤运算符全集（FilterOperator，06-ACPs-spec-ADP §4.2.1 逐字 34 个）──
+export const FILTER_OPERATORS = [
+  // 通用：等值与存在性
+  'eq', 'ne', 'exists',
+  // 比较：数值、日期、字符串字典序
+  'gt', 'gte', 'lt', 'lte', 'between',
+  // 集合：值列表匹配
+  'in', 'nin',
+  // 字符串：模式匹配（默认大小写不敏感）
+  'contains', 'notContains', 'startsWith', 'endsWith',
+  // 字符串：大小写敏感变体（Cs = Case Sensitive）
+  'eqCs', 'neCs', 'inCs', 'ninCs', 'containsCs', 'notContainsCs', 'startsWithCs', 'endsWithCs',
+  // 数组：集合运算
+  'anyOf', 'allOf', 'noneOf', 'size', 'sizeGt', 'sizeGte', 'sizeLt', 'sizeLte',
+  // Map/对象：键检查
+  'hasKey', 'hasNoKey', 'hasAnyKey', 'hasAllKeys',
+];
+
+// ── ADP 错误码（06-ACPs-spec-ADP §4.1.2 逐字）──
+export const ADP_ERROR = {
+  MISSING_QUERY: { code: 40001, message: 'MissingQuery' },
+  FORWARD_DEPTH_LIMIT_INVALID: { code: 40002, message: 'ForwardDepthLimitInvalid' },
+  FORWARD_CHAIN_INVALID: { code: 40003, message: 'ForwardChainInvalid' },
+  FILTER_INVALID: { code: 40004, message: 'FilterInvalid' },
+  FORWARD_FANOUT_LIMIT_INVALID: { code: 40005, message: 'ForwardFanoutLimitInvalid' },
+  BAD_REQUEST: { code: 40000, message: 'BadRequest' },
+  INTERNAL_ERROR: { code: 50001, message: 'InternalError' },
+};
+
+// ── 请求校验（对齐 discovery-server validator.py + schema.py 语义）──
+// 返回 { error } 或 null。error = { code, message, data? }（CommonResponse.error 形态）
+export function validateDiscoveryRequest(raw = {}) {
+  const error = (e, data) => ({ error: { code: e.code, message: e.message, data } });
+
+  // type 合法性
+  const type = raw.type ?? QUERY_TYPE_EXPLICIT;
+  if (!QUERY_TYPES.includes(type)) {
+    return error(ADP_ERROR.BAD_REQUEST, '无效的查询类型: ' + JSON.stringify(type) + '，允许: ' + QUERY_TYPES.join('/'));
+  }
+
+  // explicit 必填 query（SDK DiscoveryRequest.validate_explicit_query）
+  if (type === QUERY_TYPE_EXPLICIT && !(typeof raw.query === 'string' && raw.query.trim().length > 0)) {
+    return error(ADP_ERROR.MISSING_QUERY, "type='explicit' 时 query 字段必填且不能为空字符串");
+  }
+
+  // filtered 必填 filter（reference _handle_filtered_discovery 语义：40000 BadRequest）
+  if (type === 'filtered' && !raw.filter) {
+    return error(ADP_ERROR.BAD_REQUEST, 'filtered 查询必须提供 filter 参数');
+  }
+
+  // forwardDepthLimit 1..5（validator.py：不在 1-5 区间 → 40002）
+  if (raw.forwardDepthLimit !== undefined && raw.forwardDepthLimit !== null
+    && (raw.forwardDepthLimit < FORWARD_DEPTH_LIMIT_MIN || raw.forwardDepthLimit > FORWARD_DEPTH_LIMIT_MAX)) {
+    return error(ADP_ERROR.FORWARD_DEPTH_LIMIT_INVALID, 'forwardDepthLimit 不在 ' + FORWARD_DEPTH_LIMIT_MIN + '-' + FORWARD_DEPTH_LIMIT_MAX + ' 区间');
+  }
+
+  // forwardFanoutLimit 1..5
+  if (raw.forwardFanoutLimit !== undefined && raw.forwardFanoutLimit !== null
+    && (raw.forwardFanoutLimit < FORWARD_FANOUT_LIMIT_MIN || raw.forwardFanoutLimit > FORWARD_FANOUT_LIMIT_MAX)) {
+    return error(ADP_ERROR.FORWARD_FANOUT_LIMIT_INVALID, 'forwardFanoutLimit 不在 ' + FORWARD_FANOUT_LIMIT_MIN + '-' + FORWARD_FANOUT_LIMIT_MAX + ' 区间');
+  }
+
+  // forwardChain AIC 安全（validator.py validata_aics_safe）
+  if (raw.forwardChain !== undefined && raw.forwardChain !== null) {
+    const chain = Array.isArray(raw.forwardChain) ? raw.forwardChain : [raw.forwardChain];
+    if (!chain.every((aic) => typeof aic === 'string' && aic.trim().length > 0)) {
+      return error(ADP_ERROR.FORWARD_CHAIN_INVALID, 'forwardChain 包含非法 AIC');
+    }
+  }
+
+  // filter 结构与运算符合法性（spec：不合法条件 → 40004 FilterInvalid）
+  if (raw.filter !== undefined && raw.filter !== null) {
+    const fe = validateFilterShape(raw.filter);
+    if (fe) return error(ADP_ERROR.FILTER_INVALID, fe);
+  }
+
+  return null;
+}
+
+// 过滤条件结构校验：field 非空字符串、op ∈ 运算符全集、value 可选
+export function validateFilterShape(filter, depth = 0) {
+  if (filter === null || typeof filter !== 'object' || Array.isArray(filter)) return 'filter 必须是对象';
+  if (depth > 3) return 'filter 嵌套深度超过建议上限 3 层';
+
+  const conditions = Array.isArray(filter.conditions) ? filter.conditions : [];
+  const groups = Array.isArray(filter.groups) ? filter.groups : [];
+  if (filter.logic !== undefined && !['and', 'or', 'not'].includes(filter.logic)) {
+    return "logic 必须是 'and' | 'or' | 'not'";
+  }
+  for (const c of conditions) {
+    if (c === null || typeof c !== 'object') return 'condition 必须是对象';
+    if (typeof c.field !== 'string' || c.field.trim().length === 0) return 'condition.field 必须是非空字符串';
+    if (!FILTER_OPERATORS.includes(c.op)) return 'condition.op 非法: ' + JSON.stringify(c.op);
+  }
+  for (const g of groups) {
+    const ge = validateFilterShape(g, depth + 1);
+    if (ge) return ge;
+  }
+  return null;
+}
+
+// limit 归一化：缺省 DISCOVERY_LIMIT_DEFAULT，钳制 [1, DISCOVERY_LIMIT_MAX]
+export function normalizeLimit(limit) {
+  if (!Number.isFinite(Number(limit))) return DISCOVERY_LIMIT_DEFAULT;
+  const n = Math.floor(Number(limit));
+  if (n < 1) return 1;
+  if (n > DISCOVERY_LIMIT_MAX) return DISCOVERY_LIMIT_MAX;
+  return n;
+}
+
+// 成功/失败响应构造（DiscoveryResponse：result 与 error 互斥，reference DiscoveryResponse.success/failure）
+export function successResponse(result) {
+  return { result };
+}
+
+export function failureResponse(code, message, data) {
+  return { error: { code, message, data } };
+}

package/lib/discovery/service.js

@@ -0,0 +1,251 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// ADP 发现服务（Agent Discovery Protocol）：独立模块，核心无感知。
+// 消费 tool-descriptor catalog（工具目录）与 agent-descriptor 目录（智能体描述），
+// 提供 POST /discover 语义查询（type: explicit/exploratory/trending/filtered）+ .well-known 预置。
+// 基准：ACPs-community v2.1.0（discovery-server/app/discovery/service.py 响应构造 + acps_sdk/adp 模型）。
+// active 语义：装配可配 discovery.enabled（默认开）；节点 active=false 不出现在查询结果（读 config 键，默认 active=true）。
+
+import {
+  QUERY_TYPES, QUERY_TYPE_EXPLICIT, ADP_ERROR, FILTER_OPERATORS,
+  validateDiscoveryRequest, normalizeLimit, successResponse, failureResponse,
+} from './schema.js';
+import { evaluateFilter } from './filter.js';
+
+const LOCAL_SERVER_AIC = 'AIC-DS-A'; // 参考实现 _build_response 默认 forwardChain 首跳占位（服务自身 AIC）
+
+// ── 内部条目模型 ──
+// entry = { aic, name, description, version, active, skills: AgentSkill[], acs: <原始描述>, acsView: <ACS 形状归一视图> }
+// AgentSkill = { id, name, description, version, tags }
+// acsView：filter 条件作用于 ACS 形状字段（aic/active/name/description/version/skills.*），
+//   与原始描述（tool 6 属性 / agent 14+8）解耦——filter 引擎不感知描述器内部字段形态。
+function toAgentSkill(skill) {
+  return {
+    id: skill.skillId ?? skill.id ?? '',
+    name: skill.name ?? '',
+    description: skill.description ?? '',
+    version: skill.version ?? '',
+    tags: Array.isArray(skill.tags) ? skill.tags : [],
+  };
+}
+
+function buildAcsView(entry) {
+  return {
+    aic: entry.aic,
+    active: entry.active,
+    name: entry.name,
+    description: entry.description,
+    version: entry.version,
+    skills: entry.skills,
+  };
+}
+
+// 节点 active 判定：config.nodes[<aic|name>].active === false → 隐藏；描述自带 active=false → 隐藏；缺省 active=true
+function isNodeActive(entry, nodes) {
+  const override = nodes?.[entry.aic] ?? nodes?.[entry.name];
+  if (override && typeof override === 'object' && override.active === false) return false;
+  if (entry.acs && typeof entry.acs === 'object' && entry.acs.active === false) return false;
+  return true;
+}
+
+export function createDiscoveryService({ catalog, agentDescriptors = [], config = {} }) {
+  // config = capabilities.discovery 解析结果（{ enabled, nodes }）
+  const nodes = (config && typeof config.nodes === 'object' && config.nodes) || {};
+
+  // ── 目录装配：工具条目（tool-descriptor catalog）+ 智能体条目（agent-descriptor 目录）──
+  const entries = [];
+
+  // 工具：每个工具 = 一条目，技能 = 工具自身（P7 载体：skill 即 tool）
+  const toolList = (catalog && typeof catalog.list === 'function') ? catalog.list() : [];
+  for (const d of toolList) {
+    const entry = {
+      aic: d.toolId ?? d.name ?? '',
+      name: d.name ?? '',
+      description: d.description ?? '',
+      version: d.version ?? '',
+      skills: [{ id: d.toolId ?? d.name ?? '', name: d.name ?? '', description: d.description ?? '', version: d.version ?? '', tags: [] }],
+      acs: d,
+      kind: 'tool',
+    };
+    entry.active = isNodeActive(entry, nodes);
+    entry.acsView = buildAcsView(entry);
+    entries.push(entry);
+  }
+
+  // 智能体：agent-descriptor 目录（每 role 一份描述）
+  for (const d of agentDescriptors) {
+    const skills = Array.isArray(d.skills) ? d.skills.map(toAgentSkill) : [];
+    const entry = {
+      aic: d.agentId ?? d.aic ?? '',
+      name: d.name ?? '',
+      description: d.description ?? '',
+      version: d.version ?? '',
+      skills,
+      acs: d,
+      kind: 'agent',
+    };
+    entry.active = isNodeActive(entry, nodes);
+    entry.acsView = buildAcsView(entry);
+    entries.push(entry);
+  }
+
+  // ── 显式查询打分（能力/名称/身份码关键词匹配；本地确定性匹配，无 LLM——诚实披露）──
+  // 参考实现 exploratory 依赖 LLM 拆解子任务；本插件为单机治理插件，无 LLM 依赖，
+  // exploratory 退化为「query 关键词匹配 + filter 过滤」（本地模式），结果 memo 标注 local。
+  function scoreEntry(entry, query) {
+    const q = String(query ?? '').trim().toLowerCase();
+    if (!q) return 0;
+    const corpus = [
+      entry.name, entry.description, entry.aic,
+      ...entry.skills.flatMap((s) => [s.id, s.name, s.description, ...s.tags]),
+    ].filter(Boolean).join(' ').toLowerCase();
+    let score = 0;
+    for (const token of q.split(/\s+/)) {
+      if (!token) continue;
+      if (corpus.includes(token)) score += 1;
+      if ((entry.name ?? '').toLowerCase() === token) score += 2; // 名称精确命中加权
+      if ((entry.aic ?? '').toLowerCase() === token) score += 2;  // 身份码精确命中加权
+    }
+    return score;
+  }
+
+  // 结果行 → DiscoveryAgentSkill：取最佳命中技能（显式查询）或首个技能
+  function toAgentSkillRow(entry, query) {
+    let skillId = '';
+    if (entry.skills.length > 0) {
+      if (query) {
+        const q = String(query).trim().toLowerCase();
+        const scored = entry.skills
+          .map((s) => ({ s, score: [s.id, s.name, s.description, ...s.tags].filter(Boolean).join(' ').toLowerCase().includes(q) ? 1 : 0 }))
+          .sort((a, b) => b.score - a.score);
+        skillId = scored[0].s.id;
+      } else {
+        skillId = entry.skills[0].id;
+      }
+    }
+    return { aic: entry.aic, skillId, ranking: 0, memo: undefined };
+  }
+
+  // 过滤 + active + limit → 结果条目（含评分）
+  function applyFilterAndActive(request, scored) {
+    const activeOnly = scored.filter((e) => e.entry.active === true);
+    const filtered = request.filter
+      ? activeOnly.filter((e) => evaluateFilter(e.entry.acsView, request.filter))
+      : activeOnly;
+    return filtered;
+  }
+
+  function buildResponse(request, rows, durationMs) {
+    // rows: [{ entry, score? }] 已按 ranking 排序
+    const acsMap = {};
+    const agentSkills = rows.map(({ entry, score }, idx) => {
+      const row = toAgentSkillRow(entry, request.type === QUERY_TYPE_EXPLICIT ? request.query : null);
+      row.ranking = idx + 1;
+      row.memo = request.type === 'trending' ? 'trending'
+        : request.type === 'filtered' ? 'Filtered query result'
+          : request.type === 'exploratory' ? 'exploratory-local (no LLM decomposition)'
+            : (score !== undefined && score > 0) ? 'keyword score: ' + score : undefined;
+      if (row.memo === undefined) delete row.memo;
+      acsMap[entry.aic] = entry.acs;
+      return row;
+    });
+
+    const group = request.type === 'filtered' ? 'filtered'
+      : request.type === 'trending' ? 'trending'
+        : request.type === 'exploratory' ? (request.query || 'exploratory')
+          : (request.query || '');
+    const agentGroups = [{ group, agentSkills }];
+    const route = {
+      forwardChain: (Array.isArray(request.forwardChain) && request.forwardChain.length > 0)
+        ? request.forwardChain
+        : [LOCAL_SERVER_AIC],
+      agentGroups,
+      status: 'ok',
+      durationMs: Math.round(durationMs),
+    };
+    return successResponse({ acsMap, agents: agentGroups, routes: [route] });
+  }
+
+  // ── discover：统一 POST /discover 语义 ──
+  function discover(raw = {}) {
+    const started = Date.now();
+    const err = validateDiscoveryRequest(raw);
+    if (err) return err; // { error: { code, message, data } }
+
+    const request = { ...raw, type: raw.type ?? QUERY_TYPE_EXPLICIT };
+    const limit = normalizeLimit(request.limit);
+
+    if (request.type === 'filtered') {
+      const rows = applyFilterAndActive(request, entries.map((entry) => ({ entry })));
+      return buildResponse(request, rows.slice(0, limit), Date.now() - started);
+    }
+
+    if (request.type === 'trending') {
+      const rows = applyFilterAndActive(request, entries.map((entry) => ({ entry })));
+      // 参考实现 discover_agents_trending：随机打散后取前 limit
+      const shuffled = [...rows].sort(() => Math.random() - 0.5);
+      return buildResponse(request, shuffled.slice(0, limit), Date.now() - started);
+    }
+
+    // explicit / exploratory：关键词打分 + 过滤
+    const scored = entries.map((entry) => ({ entry, score: scoreEntry(entry, request.query) }));
+    const rows = applyFilterAndActive(request, scored);
+    const sorted = request.type === QUERY_TYPE_EXPLICIT
+      ? [...rows].sort((a, b) => b.score - a.score)
+      : [...rows].sort((a, b) => String(a.entry.name).localeCompare(String(b.entry.name)));
+    // 显式查询：score=0 表示无命中 → 仅返回有命中条目（与参考实现检索语义一致）
+    const matched = request.type === QUERY_TYPE_EXPLICIT ? sorted.filter((r) => r.score > 0) : sorted;
+    return buildResponse(request, matched.slice(0, limit), Date.now() - started);
+  }
+
+  // ── .well-known 预置：声明发现服务地址/协议版本/能力概要 ──
+  function wellKnown() {
+    return {
+      protocol: 'ACPs',
+      protocolVersion: '02.01', // ACPs v2.1.0（参考实现 ACS protocolVersion 示例）
+      service: 'dsh-punky-swarm',
+      discovery: {
+        endpoint: '/api/dsh-punky-swarm/discover',
+        transport: 'HTTP_JSON',
+        security: ['mutualTLS'],
+      },
+      capabilities: {
+        queryTypes: QUERY_TYPES,
+        defaultLimit: 5,
+        maxLimit: 50,
+        filterOperators: FILTER_OPERATORS,
+      },
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  return {
+    discover,
+    wellKnown,
+    // 只读快照（测试/诊断用）
+    stats: () => ({
+      enabled: config.enabled !== false,
+      entries: entries.length,
+      tools: entries.filter((e) => e.kind === 'tool').length,
+      agents: entries.filter((e) => e.kind === 'agent').length,
+      active: entries.filter((e) => e.active === true).length,
+    }),
+  };
+}
+
+export { ADP_ERROR };

package/lib/hot/config-watch.js

@@ -0,0 +1,252 @@
+/*
+Copyright (C) 2025-2026 Punky
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// lib/hot/config-watch.js —— R1 热更新运行时（能力开关实时生效，叠加非替换）
+// 设计依据：exec/panel-design.md §3.1（触发源/传播/生效语义）+ §3.1.5（判定语义双套保留、值传播）
+// 链路：<root>/config/runtime.json（JSON）──fs.watch + 防抖 300ms──▶ 原子读重试 ──▶ 覆盖键校验 ──▶
+//       deepMerge（导出复用 assembly/schema.js，禁止复制）──▶ 新快照 ──▶ onChange({key,value,config}) 广播
+// 语义：
+//   - 叠加非替换：只影响被覆盖键的后续读取；不写任何静态文件、不改变 cordis.patch.yml 读取结果（D2）
+//   - 缺省 {} → 快照 = 静态 config 原样（零行为变化，启动不广播）
+//   - 覆盖键校验：仅既有 schema 路径（注册表能力根 + 插件消费配置段），拒绝未知顶层键/未知 capabilities 子键
+//   - 快照 diff：无变化键不广播（防 fs.watch 重复事件抖动）
+//   - 坏 JSON / 读取失败：保持旧快照零行为变化（不广播），warn 留痕
+//   - 零新依赖：node:fs watch + JSON.parse（D1）
+// 实施回注（本环境实测，2026-08-29）：设计 §3.1.3「对文件所在目录 watch」在本部署（Windows/Node v24）不可用——
+//   目录级 fs.watch 在目录内任意文件写入/重命名时触发 libuv 断言崩溃（src\win\fs-event.c:72，原生 abort 不可捕获，
+//   探针复现：direct write 与 tmp+rename 两种写入模式均崩）。改为「文件级 fs.watch（runtime.json 直 watch）+
+//   存在性轮询 bootstrap（文件缺失时低频探测，出现即建 watch + 触发一次重读）」。文件级 watch 在本环境实测稳定
+//   （direct write→change 事件、tmp+rename→rename 事件均正常，探针通过）。此回注写入 exec/panel-a-fix.md。
+// 生命周期：start()（幂等）/ stop()（幂等）/ dispose()；watcher/timer 均 unref（不阻塞进程退出）
+// 宿主事件广播由装配侧（index.js）承担：ctx.emit('dsh-punky-swarm/config.changed', payload)；
+//   本模块只负责文件 watch → 快照 → onChange 回调（可单测，无宿主依赖）
+import { watch, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { deepMerge, CAPABILITY_REGISTRY } from '../assembly/schema.js';
+
+// cordis 总线事件名（config.changed 广播契约；装配侧 ctx.emit 用）
+export const CONFIG_CHANGED_EVENT = 'dsh-punky-swarm/config.changed';
+
+const DEFAULT_DEBOUNCE_MS = 300;   // 防抖窗口（设计 §3.1.3）
+const PARSE_RETRY_MS = 50;         // 原子读重试间隔（写半文件/并发写窗口）
+const PARSE_RETRY_MAX = 4;         // 重试上限（仍失败 → 保持旧快照）
+const DEFAULT_POLL_MS = 1000;      // 存在性轮询间隔（文件缺失 bootstrap；文件级 watch 需文件存在）
+
+// 允许的 runtime.json 顶层键：注册表能力根（aip/acps/capabilities）+ 插件消费的非能力配置段
+// （mailbox/resume/ratchet/escalation）。热更新只做值传播、只覆盖既有 schema 路径——
+// 拒绝未知顶层键防拼写漂移产生幽灵配置（设计 §3.1.3「拒绝未知顶层键」；契约验收④）
+export const ALLOWED_TOP_KEYS = new Set([
+  'aip', 'acps', 'capabilities',
+  'mailbox', 'resume', 'ratchet', 'escalation',
+]);
+
+// capabilities 子键白名单（注册表 path[0]==='capabilities' 的既有键）——
+// 拒绝 capabilities.<未知> 幽灵配置（discovery/verify/watch/worktree/budget/trajectory/logs/topic）
+export const ALLOWED_CAPS_KEYS = new Set(
+  CAPABILITY_REGISTRY.filter((e) => e.path[0] === 'capabilities').map((e) => e.path[1]),
+);
+
+// 覆盖层校验（纯函数，单测面）：返回 { ok, errors }
+export function validateOverlay(overlay) {
+  const errors = [];
+  if (overlay === null || typeof overlay !== 'object' || Array.isArray(overlay)) {
+    return { ok: false, errors: ['runtime overlay must be a JSON object'] };
+  }
+  for (const [k, v] of Object.entries(overlay)) {
+    if (!ALLOWED_TOP_KEYS.has(k)) {
+      errors.push('unknown top-level key: ' + k + ' (allowed: ' + [...ALLOWED_TOP_KEYS].join(', ') + ')');
+      continue;
+    }
+    if (k === 'capabilities' && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      for (const ck of Object.keys(v)) {
+        if (!ALLOWED_CAPS_KEYS.has(ck)) {
+          errors.push('unknown capabilities key: ' + ck + ' (allowed: ' + [...ALLOWED_CAPS_KEYS].join(', ') + ')');
+        }
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// 原子读：JSON.parse 失败短等待重试（原子写 = tmp+rename，读者只会看到旧或新完整文件；
+// 首次创建窗口仍可能读到半文件——重试兜底）；重试耗尽抛错（保持旧快照由调用方处置）
+async function readOverlayFile(file) {
+  for (let i = 0; i < PARSE_RETRY_MAX; i++) {
+    try {
+      if (!existsSync(file)) return {};
+      const parsed = JSON.parse(readFileSync(file, 'utf8'));
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('runtime.json must be a JSON object');
+      }
+      return parsed;
+    } catch (e) {
+      if (i === PARSE_RETRY_MAX - 1) throw e;
+      await sleep(PARSE_RETRY_MS * (i + 1));
+    }
+  }
+  return {};
+}
+
+export function createConfigWatcher({ root, config, onChange, logger, debounceMs = DEFAULT_DEBOUNCE_MS, useWatcher = true, pollMs = DEFAULT_POLL_MS } = {}) {
+  const configDir = join(root, 'config');
+  const runtimeFile = join(configDir, 'runtime.json');
+  const log = logger ?? null;
+  let snapshot = config;       // 缺省 = 静态 config 原样（零行为变化）
+  let overlay = {};            // 当前生效覆盖层
+  let fileWatcher = null;      // 文件级 watch（本环境目录级 watch 触发 libuv 断言崩溃，实施回注）
+  let existenceTimer = null;   // 文件缺失 bootstrap 轮询
+  let debounceTimer = null;
+  let started = false;
+  let disposed = false;
+
+  function mergeAndNotify(nextOverlay) {
+    const next = deepMerge(config, nextOverlay);
+    // 快照 diff：只广播实际变化的顶层键（无变化键不广播——防 fs.watch 重复事件/无意义变更抖动）
+    const changed = [];
+    const keys = new Set([...Object.keys(snapshot), ...Object.keys(next)]);
+    for (const k of keys) {
+      if (JSON.stringify(snapshot[k]) !== JSON.stringify(next[k])) changed.push(k);
+    }
+    if (changed.length === 0) return { changed: [] };
+    snapshot = next;
+    for (const k of changed) {
+      try {
+        onChange?.({ key: k, value: next[k], config: next });
+      } catch (e) {
+        log?.warn?.('[dsh-punky-swarm] hot config onChange failed: ' + String(e?.message ?? e));
+      }
+    }
+    log?.info?.('[dsh-punky-swarm] runtime config applied: ' + changed.join(', ') + '（热更新叠加，静态配置零改动）');
+    return { changed };
+  }
+
+  // 重读 runtime.json → 校验 → 合并 → 广播（坏 JSON/未知键 → 保持旧快照零行为变化）
+  async function reload() {
+    if (disposed) return { ok: false };
+    let nextOverlay;
+    try {
+      nextOverlay = await readOverlayFile(runtimeFile);
+    } catch (e) {
+      log?.warn?.('[dsh-punky-swarm] runtime.json read failed (keep previous snapshot): ' + String(e?.message ?? e));
+      return { ok: false, reason: 'read-failed' };
+    }
+    const v = validateOverlay(nextOverlay);
+    if (!v.ok) {
+      log?.warn?.('[dsh-punky-swarm] runtime.json overlay rejected (keep previous snapshot): ' + v.errors.join('; '));
+      return { ok: false, reason: 'invalid-overlay', errors: v.errors };
+    }
+    overlay = nextOverlay;
+    return { ok: true, ...mergeAndNotify(nextOverlay) };
+  }
+
+  async function handleFsChange() {
+    if (disposed || !started) return;
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => { reload().catch(() => {}); }, debounceMs);
+  }
+
+  // 文件级 watch 建立/重建（幂等）：每次事件后重建以跟随原子替换（tmp+rename 换 inode）；
+  // 文件缺失 → 存在性轮询 bootstrap（低频，unref），出现后建 watch + 触发一次重读
+  function ensureWatching() {
+    if (disposed || !started) return;
+    if (fileWatcher) {
+      try { fileWatcher.close(); } catch {}
+      fileWatcher = null;
+    }
+    if (!existsSync(runtimeFile)) {
+      if (!existenceTimer) {
+        existenceTimer = setInterval(() => {
+          if (disposed || !started) { clearInterval(existenceTimer); existenceTimer = null; return; }
+          if (existsSync(runtimeFile)) {
+            clearInterval(existenceTimer); existenceTimer = null;
+            ensureWatching();
+            handleFsChange().catch(() => {}); // 文件出现 → 重读一次（覆盖建 watch 前的首次写入）
+          }
+        }, pollMs);
+        if (typeof existenceTimer.unref === 'function') existenceTimer.unref();
+      }
+      return;
+    }
+    try {
+      fileWatcher = watch(runtimeFile, () => {
+        ensureWatching(); // 跟随原子替换重建（幂等）
+        handleFsChange().catch(() => {});
+      });
+      if (typeof fileWatcher.unref === 'function') fileWatcher.unref();
+      fileWatcher.on?.('error', (e) => {
+        log?.warn?.('[dsh-punky-swarm] runtime.json watch error (config hot reload degraded): ' + String(e?.message ?? e));
+        ensureWatching();
+      });
+    } catch (e) {
+      log?.warn?.('[dsh-punky-swarm] runtime.json watch failed (config hot reload disabled, restart to apply): ' + String(e?.message ?? e));
+      fileWatcher = null;
+    }
+  }
+
+  function start() {
+    if (started) return { started: true, snapshot };
+    started = true;
+    mkdirSync(configDir, { recursive: true });
+    // 初始 overlay 同步读取（启动不广播——启动时静态 config 即现状；缺省 {} → 快照 = 静态 config 原样）
+    if (existsSync(runtimeFile)) {
+      try {
+        const init = JSON.parse(readFileSync(runtimeFile, 'utf8'));
+        if (init !== null && typeof init === 'object' && !Array.isArray(init)) {
+          const v = validateOverlay(init);
+          if (v.ok) {
+            overlay = init;
+            snapshot = deepMerge(config, init);
+          } else {
+            log?.warn?.('[dsh-punky-swarm] runtime.json initial overlay rejected (use static config): ' + v.errors.join('; '));
+          }
+        } else {
+          log?.warn?.('[dsh-punky-swarm] runtime.json initial overlay must be a JSON object (use static config)');
+        }
+      } catch (e) {
+        log?.warn?.('[dsh-punky-swarm] runtime.json initial read failed (use static config): ' + String(e?.message ?? e));
+      }
+    }
+    // 文件级 watch（实施回注：本环境目录级 watch 触发 libuv 断言崩溃，改直 watch 文件）+ 存在性轮询 bootstrap
+    if (useWatcher && typeof watch === 'function') {
+      ensureWatching();
+    }
+    return { started: true, snapshot };
+  }
+
+  function stop() {
+    started = false;
+    if (debounceTimer) { clearTimeout(debounceTimer); debounceTimer = null; }
+    if (fileWatcher) { try { fileWatcher.close(); } catch {} fileWatcher = null; }
+    if (existenceTimer) { clearInterval(existenceTimer); existenceTimer = null; }
+    return { stopped: true };
+  }
+
+  function dispose() {
+    disposed = true;
+    stop();
+  }
+
+  function readSnapshot() {
+    return snapshot;
+  }
+
+  return { start, stop, dispose, reload, readSnapshot, validateOverlay, runtimeFile, eventName: CONFIG_CHANGED_EVENT };
+}