dsh-kingdom 0.3.1

package/lib/core/task.js

@@ -0,0 +1,93 @@
+/**
+ * dsh-kingdom — Task 状态机（Phase 2，Owner 裁决 1）。
+ *
+ * 冻结的状态机：
+ *   CREATED → ASSIGNED → RUNNING → REVIEW → DONE / FAILED
+ *   REVIEW → RUNNING 表示 REWORK（同一 Worker Binding，attempt_no + 1）
+ * 不引入 PLANNED。
+ *
+ * REVIEW 语义 = “Worker 已提交一个可供 Supervisor 审查的 Result Claim，
+ * 但该 Claim 尚未成为任务完成事实”。这是 Phase 2 的核心治理不变量：
+ * **Claim ≠ Fact**。
+ *
+ * 本模块**零 schema 依赖**：只描述合法转移，不碰 SQLite。
+ * 裁决 3 已现场确认 tasks.status 无 CHECK 约束，因此状态机只活在 Core 代码层，
+ * 零 migration。
+ */
+/** 冻结的 Task 状态全集（Phase 2 不新增状态）。 */
+export const TASK_STATUSES = ['CREATED', 'ASSIGNED', 'RUNNING', 'REVIEW', 'DONE', 'FAILED'];
+/**
+ * 唯一合法转移表（Owner 裁决 1 冻结）。
+ *
+ * - RUNNING → REVIEW：结构化 Worker Claim 到达（**不论 Claim 自称成功还是失败**）。
+ * - RUNNING → FAILED：executor 客观失败（宿主观察到的运行事实，非 Worker 自述，裁决 6）。
+ * - REVIEW  → DONE / RUNNING / FAILED：Supervisor 的 ACCEPT / REWORK / FAIL 决定。
+ * - DONE / FAILED 为 Phase 2 终态（裁决 6）。
+ */
+export const TASK_TRANSITIONS = {
+    CREATED: ['ASSIGNED'],
+    ASSIGNED: ['RUNNING'],
+    RUNNING: ['REVIEW', 'FAILED'],
+    REVIEW: ['DONE', 'RUNNING', 'FAILED'],
+    DONE: [],
+    FAILED: [],
+};
+/** Phase 2 终态：不可再转移。 */
+export const TERMINAL_TASK_STATUSES = ['DONE', 'FAILED'];
+/** Supervisor 审查决定（冻结三选一）。 */
+export const REVIEW_DECISIONS = ['ACCEPT', 'REWORK', 'FAIL'];
+/** ACCEPT/REWORK/FAIL → 目标状态的唯一映射。 */
+export const REVIEW_DECISION_TARGET = {
+    ACCEPT: 'DONE',
+    REWORK: 'RUNNING',
+    FAIL: 'FAILED',
+};
+/** 非法状态转移。抛出即表示调用方试图绕过治理闭环。 */
+export class TaskTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to) {
+        super(`非法 Task 状态转移：${from} → ${to}。`
+            + `${from} 的合法后继为 ${TASK_TRANSITIONS[from].length > 0 ? TASK_TRANSITIONS[from].join(' / ') : '（终态，无后继）'}。`);
+        this.name = 'TaskTransitionError';
+        this.from = from;
+        this.to = to;
+    }
+}
+/** 未知状态字符串（库里读到不认识的值时 fail-loud，不静默降级）。 */
+export class UnknownTaskStatusError extends Error {
+    constructor(value) {
+        super(`未知 Task 状态 "${value}"，合法值：${TASK_STATUSES.join(' / ')}。`);
+        this.name = 'UnknownTaskStatusError';
+    }
+}
+/** 是否为合法状态字符串。 */
+export function isTaskStatus(value) {
+    return TASK_STATUSES.includes(value);
+}
+/** 把库里的 TEXT 状态收敛为 TaskStatus；不认识就抛（不猜、不兜底）。 */
+export function asTaskStatus(value) {
+    if (!isTaskStatus(value))
+        throw new UnknownTaskStatusError(value);
+    return value;
+}
+/** 是否终态。 */
+export function isTerminalTaskStatus(status) {
+    return TERMINAL_TASK_STATUSES.includes(status);
+}
+/** 纯查询：from → to 是否合法。不抛错。 */
+export function canTransition(from, to) {
+    return TASK_TRANSITIONS[from].includes(to);
+}
+/**
+ * 状态机唯一入口：校验并返回目标状态，非法即抛。
+ *
+ * 治理纪律：任何写 tasks.status 的代码路径都必须先经过这里
+ * （见 KingdomStore.transitionTask —— 全库唯一的 status UPDATE）。
+ */
+export function transition(from, to) {
+    if (!canTransition(from, to))
+        throw new TaskTransitionError(from, to);
+    return to;
+}
+//# sourceMappingURL=task.js.map

package/lib/core/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/core/task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oCAAoC;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAA;AAIpG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA8C;IACzE,OAAO,EAAE,CAAC,UAAU,CAAC;IACrB,QAAQ,EAAE,CAAC,SAAS,CAAC;IACrB,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC7B,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC;IACrC,IAAI,EAAE,EAAE;IACR,MAAM,EAAE,EAAE;CACX,CAAA;AAED,wBAAwB;AACxB,MAAM,CAAC,MAAM,sBAAsB,GAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;AAE/E,8BAA8B;AAC9B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAA;AAIrE,sCAAsC;AACtC,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACxE,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,SAAS;IACjB,IAAI,EAAE,QAAQ;CACf,CAAA;AAED,+BAA+B;AAC/B,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,CAAY;IAChB,EAAE,CAAQ;IAEnB,YAAY,IAAgB,EAAE,EAAU;QACtC,KAAK,CACH,gBAAgB,IAAI,MAAM,EAAE,GAAG;cAC7B,GAAG,IAAI,WAAW,gBAAgB,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAC3G,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED,2CAA2C;AAC3C,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,KAAa;QACvB,KAAK,CAAC,eAAe,KAAK,SAAS,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAChE,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF;AAED,kBAAkB;AAClB,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAQ,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC7D,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAA;IACjE,OAAO,KAAK,CAAA;AACd,CAAC;AAED,YAAY;AACZ,MAAM,UAAU,oBAAoB,CAAC,MAAkB;IACrD,OAAO,sBAAsB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAChD,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,aAAa,CAAC,IAAgB,EAAE,EAAc;IAC5D,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAE,EAAc;IACzD,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;QAAE,MAAM,IAAI,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACrE,OAAO,EAAE,CAAA;AACX,CAAC"}

package/lib/core/territory.js

@@ -0,0 +1,47 @@
+/**
+ * dsh-kingdom — Territory 基础 CRUD（Phase 1）。
+ * Territory 是长期资源/上下文边界，非权限链节点（与 Role 无关）。
+ * 状态仅 ACTIVE | ARCHIVED（简单两态，不实现复杂状态机）。
+ */
+import { randomUUID } from 'node:crypto';
+export function createTerritory(store, input) {
+    const name = input.name.trim();
+    if (!name)
+        return '错误：领地名称不能为空。';
+    const existing = store.getTerritoryByName(input.kingdomId, name);
+    if (existing)
+        return `领地「${name}」已存在（id=${existing.territory_id}），未重复创建。`;
+    const now = new Date().toISOString();
+    const territory = {
+        territory_id: randomUUID(),
+        kingdom_id: input.kingdomId,
+        name,
+        workspace_path: input.workspacePath?.trim() || null,
+        summary: input.summary?.trim() || null,
+        supervisor_binding_id: null,
+        status: 'ACTIVE',
+        created_at: now,
+    };
+    store.insertTerritory(territory);
+    store.appendEvent({
+        event_id: randomUUID(),
+        kingdom_id: input.kingdomId,
+        event_type: 'TERRITORY_CREATED',
+        actor_role: null,
+        actor_id: null,
+        target_type: 'territory',
+        target_id: territory.territory_id,
+        payload_json: JSON.stringify({ name, workspace_path: territory.workspace_path }),
+        created_at: now,
+    });
+    return `已创建领地「${name}」（id=${territory.territory_id}${territory.workspace_path ? `，工作区 ${territory.workspace_path}` : ''}）。`;
+}
+export function listTerritories(store, kingdomId) {
+    const rows = store.listTerritories(kingdomId);
+    if (rows.length === 0)
+        return '当前王国还没有领地。可创建第一个，例如“给当前项目建立一个 RAG 研发领”。';
+    return rows
+        .map((t) => `- ${t.name}（${t.status}${t.workspace_path ? `，${t.workspace_path}` : ''}${t.summary ? `，${t.summary}` : ''}）`)
+        .join('\n');
+}
+//# sourceMappingURL=territory.js.map

package/lib/core/territory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"territory.js","sourceRoot":"","sources":["../../src/core/territory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAUxC,MAAM,UAAU,eAAe,CAAC,KAAmB,EAAE,KAA2B;IAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAC9B,IAAI,CAAC,IAAI;QAAE,OAAO,cAAc,CAAA;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;IAChE,IAAI,QAAQ;QAAE,OAAO,MAAM,IAAI,WAAW,QAAQ,CAAC,YAAY,UAAU,CAAA;IAEzE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACpC,MAAM,SAAS,GAAG;QAChB,YAAY,EAAE,UAAU,EAAE;QAC1B,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,IAAI;QACJ,cAAc,EAAE,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,IAAI;QACnD,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI;QACtC,qBAAqB,EAAE,IAAI;QAC3B,MAAM,EAAE,QAAQ;QAChB,UAAU,EAAE,GAAG;KAChB,CAAA;IACD,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,CAAA;IAChC,KAAK,CAAC,WAAW,CAAC;QAChB,QAAQ,EAAE,UAAU,EAAE;QACtB,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,UAAU,EAAE,mBAAmB;QAC/B,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,WAAW;QACxB,SAAS,EAAE,SAAS,CAAC,YAAY;QACjC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,cAAc,EAAE,CAAC;QAChF,UAAU,EAAE,GAAG;KAChB,CAAC,CAAA;IACF,OAAO,SAAS,IAAI,QAAQ,SAAS,CAAC,YAAY,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAA;AAC7H,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAmB,EAAE,SAAiB;IACpE,MAAM,IAAI,GAAmB,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,CAAA;IAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,yCAAyC,CAAA;IACvE,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,CAAe,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;SACxI,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}

package/lib/gui/contract.js

@@ -0,0 +1,53 @@
+/**
+ * dsh-kingdom — 插件 ↔ GUI 的线上契约（Phase 3）。
+ *
+ * ## 唯一架构原则
+ *
+ * ```text
+ * 插件输出治理事实和活动语义
+ * GUI 决定使用哪个人物、场景和动画
+ * ```
+ *
+ * 因此本文件里**不会**出现 `chancellor.png`、`sleep.gif`、
+ * `sprite.knight.default.forge.work.idle` 之类的美术知识。
+ * 插件只输出 `{ role, state, activity }`，这正是 GUI 端 Visual Resolver 的输入
+ * （另外两维 `skin` / `scene` 属于 GUI 部署配置，插件不参与）。
+ *
+ * 角色、模型、工具、运行时与皮肤因此保持解耦：
+ * 换一套贴图、换一个场景、把骑士换成别的形象，插件一行都不用改。
+ *
+ * ## 两类事实必须分开读
+ *
+ * - `TaskView.status`   —— 治理事实：组织对这件事的裁定进度。
+ * - `ExecutionView.state` —— 运行事实：某一次执行此刻的状况。
+ *
+ * `Task.RUNNING` **不代表**人物正在工作（REWORK 后任务立刻回 RUNNING，
+ * 但新 Execution 还没创建）。GUI 判断"是否播放工作动画"必须看 Execution。
+ */
+/** 组织角色。GUI 自行决定每个角色用哪个人物形象。 */
+export const ACTOR_ROLES = ['OWNER', 'CHANCELLOR', 'SUPERVISOR', 'WORKER'];
+/**
+ * 人物状态（Resolver 的 `state` 维）。
+ *
+ * `absent` 表示该角色没有绑定：GUI 应当**保留组织节点与姓名牌**，只是不渲染人物 Sprite。
+ *
+ * 这份清单是**契约的一部分**：GUI 侧 Visual Resolver 必须逐个处理它们，
+ * 漏掉任何一个都会让人物静默退化成 idle。改动本数组前请同步 GUI。
+ */
+export const ACTOR_STATES = [
+    'absent',
+    'idle',
+    'planning',
+    'assigning',
+    'working',
+    'sleeping',
+    'reviewing',
+    'waiting',
+    'confused',
+    'celebrating',
+];
+/** GUI 契约版本。破坏性变更时递增，GUI 应拒绝不认识的版本。 */
+export const GUI_SCHEMA_VERSION = 1;
+/** transient 表演动作的默认存活窗口（毫秒）。GUI 轮询 1–2s，足够捕捉。 */
+export const TRANSIENT_WINDOW_MS = 3500;
+//# sourceMappingURL=contract.js.map

package/lib/gui/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/gui/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gCAAgC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAA;AAInF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,MAAM;IACN,UAAU;IACV,WAAW;IACX,SAAS;IACT,UAAU;IACV,WAAW;IACX,SAAS;IACT,UAAU;IACV,aAAa;CACL,CAAA;AA0OV,uCAAuC;AACvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAEnC,kDAAkD;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAA"}

package/lib/gui/server.js

@@ -0,0 +1,204 @@
+/**
+ * dsh-kingdom — 本地 GUI 连接通道（Phase 3，P0-4）。
+ *
+ * 浏览器 GUI **不能**直接读本地 `kingdom.db`，所以由插件在本机开一个
+ * 只监听 `127.0.0.1` 的小型 HTTP 服务，把结构化 Snapshot / Task Detail /
+ * 事件增量暴露出去，并转发写命令。
+ *
+ * Beta 采用**轮询**（建议 1–2s 拉一次 `/api/snapshot`，或用 `revision` 先探再拉），
+ * 不做完整实时推送。`revision` 与事件 `seq` 让轮询也能拿到确定的顺序语义。
+ *
+ * ## 安全姿态（本地开发工具，非生产服务）
+ *
+ * - **默认关闭**：`guiPort` 缺省为 0。要用 GUI 必须显式配置端口——
+ *   插件不会在用户不知情时打开监听端口。
+ * - 只绑定 `127.0.0.1`，不监听外部网卡。
+ * - 写命令要求自定义头 `X-Kingdom-Client`：自定义头会强制浏览器发预检，
+ *   从而挡掉简单表单式 CSRF（恶意页面无法向本机端口静默提交命令）。
+ * - 可选 `guiToken`：设置后所有请求需带 `Authorization: Bearer <token>`。
+ * - 鉴权诚实度由 snapshot 的 `auth.trustLevel` 如实声明，GUI 必须显示。
+ */
+import { createServer } from 'node:http';
+import { GUI_SCHEMA_VERSION } from './contract.js';
+/** 写命令必须带的自定义头（存在即可，值不校验）。 */
+const CLIENT_HEADER = 'x-kingdom-client';
+const COMMANDS = new Set([
+    'plan', 'assign', 'start', 'review',
+    'execution.pause', 'execution.resume', 'execution.abort',
+]);
+function corsOrigin(req, allow) {
+    const origin = req.headers.origin;
+    if (allow.includes('*'))
+        return origin ?? '*';
+    if (typeof origin === 'string' && allow.includes(origin))
+        return origin;
+    return null;
+}
+function applyCors(req, res, allow) {
+    const origin = corsOrigin(req, allow);
+    if (origin)
+        res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Vary', 'Origin');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', `Content-Type, Authorization, ${CLIENT_HEADER}`);
+    res.setHeader('Access-Control-Max-Age', '600');
+}
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(text),
+        'Cache-Control': 'no-store',
+    });
+    res.end(text);
+}
+function sendError(res, status, errorCode, message) {
+    sendJson(res, status, { ok: false, errorCode, message });
+}
+async function readJsonBody(req, limitBytes = 1_000_000) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        size += buf.length;
+        if (size > limitBytes)
+            throw new Error('request body too large');
+        chunks.push(buf);
+    }
+    if (size === 0)
+        return {};
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('request body must be a JSON object');
+    }
+    return parsed;
+}
+/**
+ * 启动本地 GUI 通道。
+ * @returns 关闭函数（挂到 ctx.effect，插件卸载/热重载时自动收回端口）。
+ */
+export function startGuiServer(handlers, options) {
+    const host = options.host ?? '127.0.0.1';
+    const allow = options.allowOrigins ?? ['*'];
+    const token = options.token?.trim() || null;
+    const server = createServer((req, res) => {
+        void handleRequest(req, res).catch((error) => {
+            if (!res.headersSent) {
+                sendError(res, 500, 'INTERNAL_ERROR', error instanceof Error ? error.message : String(error));
+            }
+            else {
+                res.end();
+            }
+        });
+    });
+    async function handleRequest(req, res) {
+        applyCors(req, res, allow);
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (token !== null && req.headers.authorization !== `Bearer ${token}`) {
+            sendError(res, 401, 'UNAUTHORIZED', 'missing or invalid bearer token');
+            return;
+        }
+        const url = new URL(req.url ?? '/', `http://${host}`);
+        const path = url.pathname.replace(/\/+$/, '') || '/';
+        if (req.method === 'GET' && (path === '/' || path === '/api/health')) {
+            sendJson(res, 200, { ok: true, service: 'dsh-kingdom', schemaVersion: GUI_SCHEMA_VERSION });
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/snapshot') {
+            sendJson(res, 200, handlers.snapshot());
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/events') {
+            const since = Number.parseInt(url.searchParams.get('since') ?? '0', 10);
+            const limit = Number.parseInt(url.searchParams.get('limit') ?? '200', 10);
+            sendJson(res, 200, handlers.eventsSince(Number.isFinite(since) && since > 0 ? since : 0, Number.isFinite(limit) && limit > 0 ? Math.min(limit, 1000) : 200));
+            return;
+        }
+        const taskMatch = /^\/api\/tasks\/([^/]+)$/u.exec(path);
+        if (req.method === 'GET' && taskMatch) {
+            const detail = handlers.taskDetail(decodeURIComponent(taskMatch[1]));
+            if (!detail) {
+                sendError(res, 404, 'TASK_NOT_FOUND', 'task not found in the current kingdom');
+                return;
+            }
+            sendJson(res, 200, detail);
+            return;
+        }
+        const commandMatch = /^\/api\/commands\/([a-z.]+)$/u.exec(path);
+        if (req.method === 'POST' && commandMatch) {
+            const name = commandMatch[1];
+            if (!COMMANDS.has(name)) {
+                sendError(res, 404, 'UNKNOWN_COMMAND', `unknown command "${name}"`);
+                return;
+            }
+            // 自定义头强制预检，挡掉简单表单式 CSRF。
+            if (req.headers[CLIENT_HEADER] === undefined) {
+                sendError(res, 400, 'MISSING_CLIENT_HEADER', `write commands require the ${CLIENT_HEADER} header`);
+                return;
+            }
+            let payload;
+            try {
+                payload = await readJsonBody(req);
+            }
+            catch (error) {
+                sendError(res, 400, 'INVALID_BODY', error instanceof Error ? error.message : String(error));
+                return;
+            }
+            const result = await handlers.command(name, payload);
+            sendJson(res, result.ok ? 200 : 409, result);
+            return;
+        }
+        sendError(res, 404, 'NOT_FOUND', `no route for ${req.method ?? 'GET'} ${path}`);
+    }
+    let retries = 0;
+    let retryTimer = null;
+    let disposed = false;
+    /**
+     * 端口占用时有界重试。
+     *
+     * HMR 的常见时序是「新实例先起、旧实例后卸」，此时端口还在旧实例手里。
+     * 不重试的话，新实例的 GUI 通道会在整个生命周期里保持死掉——
+     * 开发时表现为「改一次代码 GUI 就再也连不上，必须整体重启 DSH」。
+     * 重试是有界的（最多 ~3 秒），避免真正的端口冲突变成无限循环。
+     */
+    const RETRY_DELAY_MS = 300;
+    const MAX_RETRIES = 10;
+    server.on('error', (error) => {
+        if (error.code === 'EADDRINUSE' && !disposed && retries < MAX_RETRIES) {
+            retries++;
+            retryTimer = setTimeout(() => {
+                retryTimer = null;
+                if (!disposed)
+                    server.listen(options.port, host);
+            }, RETRY_DELAY_MS);
+            // 重试期间保持安静；只有最终放弃才告警，避免刷屏。
+            if (retries === MAX_RETRIES) {
+                options.logger?.warn(`dsh-kingdom GUI 通道：端口 ${options.port} 持续被占用，`
+                    + `已重试 ${MAX_RETRIES} 次仍失败，本次加载不提供 GUI 通道（请换 guiPort 或检查残留进程）。`);
+            }
+            return;
+        }
+        if (!disposed) {
+            options.logger?.warn(`dsh-kingdom GUI 通道启动失败（${error.message}）`);
+        }
+    });
+    server.listen(options.port, host, () => {
+        retries = 0;
+        options.logger?.info(`dsh-kingdom GUI 通道已监听 http://${host}:${options.port}`
+            + `（snapshot / tasks / events / commands${token ? '，已启用 bearer token' : ''}）`);
+    });
+    return () => {
+        disposed = true;
+        if (retryTimer) {
+            clearTimeout(retryTimer);
+            retryTimer = null;
+        }
+        server.close();
+        server.closeAllConnections?.();
+    };
+}
+//# sourceMappingURL=server.js.map

package/lib/gui/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/gui/server.ts"],"names":[],"mappings":"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"}