dsh-kingdom 0.3.1

package/lib/types/core/db.d.ts

@@ -0,0 +1,261 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type TaskStatus } from './task.js';
+import { type ExecutionState } from './execution.js';
+/**
+ * 记录在 kingdoms.schema_version 上的值。
+ *
+ * Phase 2 **刻意保持 1**：本插件没有任何按版本号分支的 migration 逻辑，
+ * 建表全部幂等，任何 0.2.0 打开的旧库都会在开库瞬间收敛到同一套 6 表结构。
+ * 此时把新库标成 2、旧库留在 1，只会制造一个「同结构不同版本号」的假差异。
+ * 真正引入破坏性 migration 时再启用这个字段作为 gate。
+ */
+export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS kingdoms (\n  kingdom_id   TEXT PRIMARY KEY,\n  name         TEXT NOT NULL,\n  created_at   TEXT NOT NULL,\n  owner_id     TEXT NOT NULL,\n  owner_name   TEXT NOT NULL,\n  schema_version INTEGER NOT NULL DEFAULT 1\n);\n\nCREATE TABLE IF NOT EXISTS territories (\n  territory_id  TEXT PRIMARY KEY,\n  kingdom_id    TEXT NOT NULL,\n  name          TEXT NOT NULL,\n  workspace_path TEXT,\n  summary       TEXT,\n  supervisor_binding_id TEXT,\n  status        TEXT NOT NULL DEFAULT 'ACTIVE',\n  created_at    TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS role_bindings (\n  binding_id   TEXT PRIMARY KEY,\n  kingdom_id   TEXT NOT NULL,\n  role_type    TEXT NOT NULL CHECK(role_type IN ('OWNER','CHANCELLOR','SUPERVISOR','WORKER')),\n  role_name    TEXT NOT NULL,\n  runtime_type TEXT NOT NULL DEFAULT 'dsh',\n  session_id   TEXT,\n  principal_id TEXT,\n  created_at   TEXT NOT NULL,\n  updated_at   TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS tasks (\n  task_id         TEXT PRIMARY KEY,\n  territory_id    TEXT NOT NULL,\n  parent_task_id  TEXT,\n  title           TEXT NOT NULL,\n  description     TEXT,\n  assigned_binding_id TEXT,\n  status          TEXT NOT NULL DEFAULT 'CREATED',\n  acceptance_criteria TEXT,\n  result_summary  TEXT,\n  created_at      TEXT NOT NULL,\n  updated_at      TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  event_id    TEXT PRIMARY KEY,\n  kingdom_id  TEXT NOT NULL,\n  event_type  TEXT NOT NULL,\n  actor_role  TEXT,\n  actor_id    TEXT,\n  target_type TEXT,\n  target_id   TEXT,\n  payload_json TEXT NOT NULL DEFAULT '{}',\n  created_at  TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS worker_results (\n  result_id          TEXT PRIMARY KEY,\n  task_id            TEXT NOT NULL,\n  attempt_no         INTEGER NOT NULL,\n  worker_binding_id  TEXT,\n  session_id         TEXT,\n  outcome            TEXT NOT NULL,\n  result_json        TEXT NOT NULL DEFAULT '{}',\n  created_at         TEXT NOT NULL,\n  UNIQUE(task_id, attempt_no)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS territories_kingdom_name_uk\n  ON territories(kingdom_id, name);\n\nCREATE TABLE IF NOT EXISTS executions (\n  execution_id       TEXT PRIMARY KEY,\n  task_id            TEXT NOT NULL,\n  attempt_no         INTEGER NOT NULL,\n  worker_binding_id  TEXT,\n  session_id         TEXT,\n  state              TEXT NOT NULL,\n  detail             TEXT,\n  started_at         TEXT NOT NULL,\n  heartbeat_at       TEXT,\n  ended_at           TEXT,\n  pause_requested_at TEXT,\n  UNIQUE(task_id, attempt_no)\n);\n\nCREATE INDEX IF NOT EXISTS executions_task_idx ON executions(task_id);\n";
+export interface KingdomRow {
+    kingdom_id: string;
+    name: string;
+    created_at: string;
+    owner_id: string;
+    owner_name: string;
+    schema_version: number;
+}
+export interface TerritoryRow {
+    territory_id: string;
+    kingdom_id: string;
+    name: string;
+    workspace_path: string | null;
+    summary: string | null;
+    supervisor_binding_id: string | null;
+    status: string;
+    created_at: string;
+}
+export interface RoleBindingRow {
+    binding_id: string;
+    kingdom_id: string;
+    role_type: string;
+    role_name: string;
+    runtime_type: string;
+    session_id: string | null;
+    principal_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface EventRow {
+    event_id: string;
+    kingdom_id: string;
+    event_type: string;
+    actor_role: string | null;
+    actor_id: string | null;
+    target_type: string | null;
+    target_id: string | null;
+    payload_json: string;
+    created_at: string;
+    /**
+     * 王国内单调递增的事件序号（GUI 排序与断流检测用）。
+     *
+     * 由 `appendEvent` 在 IMMEDIATE 事务里分配，保证「读 MAX + 写入」原子。
+     * GUI 用它判断：哪个事件更新、是否漏了事件、以及**旧事件不得让已停止的人物重新出现**。
+     * 旧库由 `ensureEventSequence()` 按 rowid（即插入顺序）回填。
+     */
+    seq: number;
+}
+/**
+ * executions 行（Phase 3 新增第 7 张表）。
+ *
+ * **与 tasks 的分工**：`tasks.status` 是治理事实（组织裁定进度），
+ * 本表是运行事实（某一次执行此刻的状况）。
+ * `Task.RUNNING` 不等于"正在执行"——REWORK 后任务立刻回 RUNNING，
+ * 但新 Execution 尚未创建。GUI 必须看本表才能决定人物是否在工作。
+ */
+export interface ExecutionRow {
+    execution_id: string;
+    task_id: string;
+    attempt_no: number;
+    worker_binding_id: string | null;
+    /** 该次执行的 one-shot subagent session id（每轮 REWORK 都是新的）。 */
+    session_id: string | null;
+    /** STARTING / RUNNING / PAUSED / COMPLETED / FAILED / ABORTED，见 ./execution.ts。 */
+    state: string;
+    /** 终止原因等诊断信息（宿主观察，非 Worker 自述）。 */
+    detail: string | null;
+    started_at: string;
+    /**
+     * 最近一次**状态转移**的时刻，不是心跳。
+     *
+     * 诚实说明：one-shot subagent 这个 seam 不提供任何进度回调
+     * （`SubagentRun` 只有 `{id, localAgent, result, dispose}`），
+     * 所以执行进行中没有任何可以周期性上报的信号，本字段在整个执行体内不会前进。
+     *
+     * **不要拿它做存活判定**：一次合法的长执行与一次挂死的执行，
+     * 在这个字段上完全无法区分。插件崩溃/重载导致的残骸由加载期回收兜底
+     * （见 task-service.ts 的 reclaimOrphanExecutions），那条路径不依赖本字段。
+     */
+    heartbeat_at: string | null;
+    ended_at: string | null;
+    /**
+     * 暂停请求时间。
+     *
+     * one-shot subagent 无法在一次 turn 中途真正挂起，因此"暂停"的诚实语义是：
+     * 请求已登记，**在下一个 attempt 边界生效**。执行中的 Execution 会保持
+     * `RUNNING` 并带 `pause_requested_at`（GUI 应显示"准备休息"而不是"已睡着"）。
+     */
+    pause_requested_at: string | null;
+}
+/** tasks 行（Phase 1 schema，Phase 2 一字未改）。status 语义见 ./task.ts。 */
+export interface TaskRow {
+    task_id: string;
+    territory_id: string;
+    parent_task_id: string | null;
+    title: string;
+    description: string | null;
+    assigned_binding_id: string | null;
+    /** 权威状态。只经 KingdomStore.transitionTask 写入（全库唯一 status UPDATE）。 */
+    status: string;
+    acceptance_criteria: string | null;
+    /** 最近一次 Worker Claim 的摘要。**是 Claim，不是完成事实**。 */
+    result_summary: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * worker_results 行（Phase 2 新增第 6 张表，Owner 裁决 4）。
+ *
+ * **语义写死：本表保存 Worker Claim，不代表 Task Fact。**
+ * 一行 = 一个 attempt 的 Worker 自述结果。Task 是否完成由 tasks.status 决定，
+ * 而 tasks.status 只能由 Supervisor 经 kingdom_review_task 推到 DONE。
+ * outcome 是 Worker 自称的 COMPLETED/FAILED/BLOCKED，**不参与**任何自动状态决策。
+ */
+export interface WorkerResultRow {
+    result_id: string;
+    task_id: string;
+    /** 第几次尝试，从 1 起；REWORK 每轮 +1。UNIQUE(task_id, attempt_no)。 */
+    attempt_no: number;
+    worker_binding_id: string | null;
+    /** 该 attempt 的 one-shot subagent session id（每轮 REWORK 都是新 session）。 */
+    session_id: string | null;
+    /** Worker 自称的结果：COMPLETED / FAILED / BLOCKED。是 Claim。 */
+    outcome: string;
+    /** 完整结构化 Claim（summary/artifacts/risks），JSON 文本。 */
+    result_json: string;
+    created_at: string;
+}
+export declare class KingdomStore {
+    readonly db: DatabaseSync;
+    /** 已打开即存在（表已保证）；记录 init 结果供 status 用 */
+    readonly existed: boolean;
+    constructor(dbPath: string);
+    /**
+     * 给 events 补上单调序号列（0.2.0 → 0.3.0 唯一一处触及既有表的变更）。
+     *
+     * 仍然是纯增量、可重复执行、无 table-rebuild：
+     * 1. `PRAGMA table_info` 做存在性 gate（`ADD COLUMN` 没有 IF NOT EXISTS）；
+     * 2. 用 rowid（= 插入顺序）回填历史行，历史顺序因此可确定地重建；
+     * 3. 索引用 `IF NOT EXISTS`。
+     *
+     * 注意 SQLite 的 `ALTER TABLE ... ADD COLUMN` 是 O(1) 元数据操作，
+     * 不重写数据页，因此旧库开库仍然是瞬时收敛。
+     */
+    private ensureEventSequence;
+    /** 关闭连接（插件卸载/重载时调用，避免句柄泄漏）。 */
+    close(): void;
+    listKingdoms(): KingdomRow[];
+    getDefaultKingdom(): KingdomRow | null;
+    insertKingdom(row: Omit<KingdomRow, 'schema_version'> & {
+        schema_version?: number;
+    }): KingdomRow;
+    listTerritories(kingdomId: string): TerritoryRow[];
+    getTerritoryByName(kingdomId: string, name: string): TerritoryRow | null;
+    getTerritoryById(territoryId: string): TerritoryRow | null;
+    insertTerritory(row: TerritoryRow): TerritoryRow;
+    listBindings(kingdomId: string): RoleBindingRow[];
+    getBindingByRole(kingdomId: string, roleType: string): RoleBindingRow | null;
+    getBindingById(bindingId: string): RoleBindingRow | null;
+    insertBinding(row: RoleBindingRow): RoleBindingRow;
+    updateBindingSession(bindingId: string, sessionId: string | null, updatedAt: string): void;
+    listEvents(kingdomId: string, limit?: number): EventRow[];
+    /**
+     * 按序号增量拉取（GUI 轮询用）：返回 seq > afterSeq 的事件，**升序**。
+     *
+     * GUI 据此判断是否漏事件（收到的首个 seq 应等于 afterSeq + 1），
+     * 漏了就重新拉一次全量 snapshot，而不是拿残缺事件流去驱动动画。
+     */
+    listEventsSince(kingdomId: string, afterSeq: number, limit?: number): EventRow[];
+    /**
+     * 王国当前 revision = 最大事件序号。
+     *
+     * 任何治理动作都会追加事件，所以这个数既是事件游标，也是"数据版本"：
+     * GUI 比较 revision 就知道要不要重绘，不必 diff 整个 snapshot。
+     */
+    revision(kingdomId: string): number;
+    /**
+     * 追加事件并分配单调 seq。
+     *
+     * 「读 MAX(seq) + INSERT」放在 IMMEDIATE 事务里，避免并发写出重复序号
+     * （SQLite 会串行化写事务）。序号在**全库**范围内单调，跨王国也不会回退。
+     */
+    appendEvent(row: Omit<EventRow, 'seq'> & {
+        seq?: number;
+    }): EventRow;
+    getTask(taskId: string): TaskRow | null;
+    /**
+     * 列出王国内任务。tasks 无 kingdom_id 列（Phase 1 schema），
+     * 经 territories 关联收敛到王国边界。
+     */
+    listTasks(kingdomId: string, filter?: {
+        territoryId?: string;
+        status?: string;
+    }): TaskRow[];
+    insertTask(row: TaskRow): TaskRow;
+    /**
+     * **全库唯一的 tasks.status 写入路径**（治理底线，Owner 裁决 1）。
+     *
+     * 先过 ./task.ts 的 transition() 校验，非法转移直接抛 TaskTransitionError，
+     * 一个字节都不会落库。任何工具都无法绕过它把 Task 直接置 DONE
+     * —— DONE 只能从 REVIEW 经 Supervisor 的 ACCEPT 决定到达。
+     *
+     * @param task 当前任务行（status 取自库，未知值 fail-loud）。
+     * @param to 目标状态。
+     * @param patch 与状态同事务落库的附带字段（如指派、Claim 摘要）。
+     * @returns 落库后的新任务行。
+     */
+    transitionTask(task: TaskRow, to: TaskStatus, patch?: {
+        assigned_binding_id?: string | null;
+        result_summary?: string | null;
+    }): TaskRow;
+    listWorkerResults(taskId: string): WorkerResultRow[];
+    latestWorkerResult(taskId: string): WorkerResultRow | null;
+    /** 已落库的最大 attempt_no；无结果时为 0。下一次尝试 = 本值 + 1。 */
+    maxAttemptNo(taskId: string): number;
+    /**
+     * executions 侧的最大 attempt_no。
+     *
+     * **不能只看 worker_results 来编下一个 attempt 号**：executor 客观失败、
+     * 被 abort、以及重载后被回收的僵尸执行都只有 Execution 行、没有 Claim 行。
+     * 只按 Claim 计数会重复发号，撞上 `UNIQUE(task_id, attempt_no)`。
+     * 下一次尝试号必须取两者的最大值再 +1（见 nextAttemptNo）。
+     */
+    maxExecutionAttemptNo(taskId: string): number;
+    /** 下一次执行应使用的 attempt 号：Claim 与 Execution 两侧取大再 +1。 */
+    nextAttemptNo(taskId: string): number;
+    insertWorkerResult(row: WorkerResultRow): WorkerResultRow;
+    getExecution(executionId: string): ExecutionRow | null;
+    listExecutions(taskId: string): ExecutionRow[];
+    latestExecution(taskId: string): ExecutionRow | null;
+    /** 王国内所有未终结的 Execution（人物应当在场的那些）。 */
+    listLiveExecutions(kingdomId: string): ExecutionRow[];
+    insertExecution(row: ExecutionRow): ExecutionRow;
+    /**
+     * **全库唯一的 executions.state 写入路径**（与 transitionTask 同构）。
+     *
+     * 先过 ./execution.ts 的 `transitionExecution()` 校验，非法转移抛错、不落库。
+     * 终态自动补 `ended_at`，避免"已结束但没有结束时间"的半截记录。
+     */
+    transitionExecution(execution: ExecutionRow, to: ExecutionState, patch?: {
+        detail?: string | null;
+        sessionId?: string | null;
+        pauseRequestedAt?: string | null;
+    }): ExecutionRow;
+    /** 登记暂停请求（不改状态；生效点见 ExecutionRow.pause_requested_at 注释）。 */
+    setExecutionPauseRequest(executionId: string, at: string | null): void;
+    statusSummary(): string;
+}

package/lib/types/core/execution.d.ts

@@ -0,0 +1,51 @@
+/**
+ * dsh-kingdom — Execution 生命周期（Phase 3 / GUI 适配）。
+ *
+ * ## 为什么 Execution 必须独立于 Task
+ *
+ * `Task.status === 'RUNNING'` **不能**可靠表示"骑士正在工作"：
+ * REWORK 之后任务立刻回到 RUNNING，但新的 Worker 执行还没启动；
+ * 此时 GUI 若按 Task.status 播放工作动画，人物就在假装干活。
+ *
+ * 所以治理事实（Task）与运行事实（Execution）分开建模：
+ *
+ * ```text
+ * Task.status      = 组织对这件事的裁定进度（CREATED..DONE/FAILED）
+ * Execution.state  = 某一次具体执行此刻的运行状况（STARTING..ABORTED）
+ * ```
+ *
+ * 一个 Task 的每个 attempt 至多一个 Execution（`UNIQUE(task_id, attempt_no)`）。
+ *
+ * 本模块与 `./task.ts` 一样**零 schema 依赖**：只描述合法转移。
+ */
+/** Execution 的全部状态。 */
+export declare const EXECUTION_STATES: readonly ["STARTING", "RUNNING", "PAUSED", "COMPLETED", "FAILED", "ABORTED"];
+export type ExecutionState = (typeof EXECUTION_STATES)[number];
+/**
+ * 合法转移。
+ *
+ * - `STARTING → RUNNING`：宿主确认执行已真正开始。
+ * - `RUNNING ↔ PAUSED`：暂停/恢复（见 `./execution.ts` 关于 one-shot 的诚实边界说明）。
+ * - `* → COMPLETED`：执行交回了合法结构化结果（**注意：这只说明跑完了，不代表任务完成**）。
+ * - `* → FAILED`：宿主观察到执行没跑出合法结果。
+ * - `* → ABORTED`：被显式终止（会话停止/用户取消），与 FAILED 区分开。
+ */
+export declare const EXECUTION_TRANSITIONS: Record<ExecutionState, readonly ExecutionState[]>;
+/** 终态：不再有后续转移，人物 Sprite 应退场。 */
+export declare const TERMINAL_EXECUTION_STATES: readonly ExecutionState[];
+/** 活跃态：人物应当在场（工作或休息）。 */
+export declare const LIVE_EXECUTION_STATES: readonly ExecutionState[];
+export declare class ExecutionTransitionError extends Error {
+    constructor(from: ExecutionState, to: string);
+}
+export declare class UnknownExecutionStateError extends Error {
+    constructor(value: string);
+}
+export declare function isExecutionState(value: string): value is ExecutionState;
+/** 库里读到的 TEXT 收敛为 ExecutionState；不认识就抛（fail-loud，不猜）。 */
+export declare function asExecutionState(value: string): ExecutionState;
+export declare function isTerminalExecutionState(state: ExecutionState): boolean;
+export declare function isLiveExecutionState(state: ExecutionState): boolean;
+export declare function canTransitionExecution(from: ExecutionState, to: ExecutionState): boolean;
+/** 状态机唯一入口：校验并返回目标状态，非法即抛。 */
+export declare function transitionExecution(from: ExecutionState, to: ExecutionState): ExecutionState;

package/lib/types/core/kingdom.d.ts

@@ -0,0 +1,34 @@
+import { KingdomStore } from './db.js';
+export interface InitResult {
+    action: 'initialized' | 'attached';
+    kingdomId: string;
+    kingdomName: string;
+    ownerId: string;
+    ownerName: string;
+    territoryCount: number;
+    bindingCount: number;
+    detail: string;
+}
+/** 当前 OS 用户名（显式名称缺失时的兜底）。 */
+export declare function currentOsUser(): string;
+export interface KingdomManagerOptions {
+    /** 显式 kingdom 名称；缺省 "My Kingdom" */
+    kingdomName?: string;
+    /** 显式 owner 名称；缺省取 OS 用户名 */
+    ownerName?: string;
+    dbPath?: string;
+}
+export declare class KingdomManager {
+    private readonly store;
+    private readonly opts;
+    constructor(options?: KingdomManagerOptions);
+    get storeHandle(): KingdomStore;
+    /**
+     * init：扫描本机 → 无 kingdom.db 则初始化，有则接入。
+     * 幂等：重复调用只接入，绝不覆盖既有数据。
+     */
+    init(): InitResult;
+    /** 重新扫描接入（不删除任何数据）。 */
+    rescan(): InitResult;
+    close(): void;
+}

package/lib/types/core/task-service.d.ts

@@ -0,0 +1,107 @@
+import type { KingdomStore } from './db.js';
+import type { WorkerExecutor } from '../worker/executor.js';
+import type { AuthView, CommandResultView } from '../gui/contract.js';
+/** 调用主体。Phase 3 的最低鉴权只认 sessionId（见 {@link AuthView}）。 */
+export interface Principal {
+    sessionId?: string | null;
+}
+export interface CommandContext {
+    kingdomId: string;
+    principal?: Principal;
+    auth: AuthView;
+}
+/**
+ * 插件加载时回收孤儿 Execution。
+ *
+ * **为什么这是安全的**：Worker 以 **one-shot in-process subagent** 执行，
+ * 它的生命周期完全绑在插件 fiber 上。插件一旦卸载/重载，那个 subagent
+ * 就不可能还活着。因此**开库时看到的任何"活跃" Execution，都必然是
+ * 上一个进程留下的残骸** —— 这不是推测，是由执行模型保证的。
+ *
+ * 不回收会怎样：Execution 永远停在 RUNNING，
+ * - GUI 看到骑士永远在工作（谎报运行状态）；
+ * - 该任务再也无法 start（被"已有未结束的 Execution"挡住）。
+ *
+ * 回收判定为 `ABORTED` 而不是 `FAILED`：这是宿主观察到的**中断**，
+ * 不是"executor 没跑出合法结果"，两者语义必须分开。
+ * 任务的治理状态**不动** —— 回收只处理运行事实，不替 Supervisor 做裁定。
+ *
+ * @returns 被回收的 Execution 数量。
+ */
+export declare function reclaimOrphanExecutions(store: KingdomStore, kingdomId: string): number;
+export interface PlanTaskInput {
+    territoryId?: string;
+    title: string;
+    description?: string;
+    acceptanceCriteria?: string;
+}
+/** 创建 Task → CREATED。要求 CHANCELLOR binding。 */
+export declare function planTask(store: KingdomStore, ctx: CommandContext, input: PlanTaskInput): CommandResultView;
+export interface AssignTaskInput {
+    taskId: string;
+    workerBindingId?: string;
+}
+/** CREATED → ASSIGNED。 */
+export declare function assignTask(store: KingdomStore, ctx: CommandContext, input: AssignTaskInput): CommandResultView;
+export interface StartTaskInput {
+    taskId: string;
+}
+/**
+ * 触发一轮 Worker 执行（执行期间阻塞等待 subagent）。
+ *
+ * 入口状态：`ASSIGNED`（首轮）或 `RUNNING`（Supervisor 刚判 REWORK）。
+ *
+ * Phase 3 增量：本轮执行会创建一条独立的 Execution 行。
+ * Task.status 与 Execution.state 从此分离——
+ * GUI 判断"骑士是否在工作"只看后者。
+ *
+ * 结局仍只有两种（裁决 6）：
+ * - 合法结构化 Claim → 落 worker_results → **RUNNING → REVIEW**（无论 Claim 自称成败）；
+ * - executor 客观失败 → **RUNNING → FAILED** + `WORKER_EXECUTION_FAILED`，且不落 Claim。
+ */
+export declare function startTask(store: KingdomStore, executor: WorkerExecutor, ctx: CommandContext, input: StartTaskInput): Promise<CommandResultView>;
+export interface ReviewTaskInput {
+    taskId: string;
+    decision: string;
+    reason?: string;
+}
+/**
+ * Supervisor 审查 Worker Claim，把 Claim 转成组织事实。
+ *
+ * - ACCEPT → DONE（+ TASK_ACCEPTED；不新增 task_reviews 表，裁决 4）
+ * - REWORK → RUNNING（同一 Worker Binding；下一次 start 会以 attempt+1 起新 Execution）
+ * - FAIL   → FAILED（终态；只有这里能把 Worker 的失败 Claim 变成组织事实）
+ */
+export declare function reviewTask(store: KingdomStore, ctx: CommandContext, input: ReviewTaskInput): CommandResultView;
+export interface ExecutionCommandInput {
+    executionId: string;
+    reason?: string;
+}
+/**
+ * 请求暂停一次执行。
+ *
+ * **诚实的语义边界**：Worker 是 one-shot subagent，宿主无法在一次 turn 中途
+ * 真正挂起它。因此：
+ * - 执行**尚未真正开始**（STARTING）→ 直接转 PAUSED，人物可以睡觉；
+ * - 执行**正在进行**（RUNNING）→ 只登记 `pause_requested_at`，状态保持 RUNNING，
+ *   `ExecutionView.pausePending = true`。GUI 应表现为"准备休息"，
+ *   **不能**直接播睡觉动画——那会谎报运行状态。
+ */
+export declare function pauseExecution(store: KingdomStore, ctx: CommandContext, input: ExecutionCommandInput): CommandResultView;
+/** 恢复执行：撤销暂停请求，或把 PAUSED 转回 RUNNING。 */
+export declare function resumeExecution(store: KingdomStore, ctx: CommandContext, input: ExecutionCommandInput): CommandResultView;
+/**
+ * 终止一次执行（ABORTED）。
+ *
+ * 与 FAILED 区分开：ABORTED 是"被显式停止"，FAILED 是"宿主观察到跑不出结果"。
+ * 终止只影响运行事实；Task 的治理状态由 Supervisor 另行裁定
+ * （任务停在 RUNNING，等待重新 start 或人工处理）。
+ * GUI 收到 SESSION_STOPPED 只移除人物 Sprite，**组织节点、姓名牌与详情保留**。
+ */
+export declare function abortExecution(store: KingdomStore, ctx: CommandContext, input: ExecutionCommandInput): CommandResultView;
+export interface ListTasksInput {
+    territoryId?: string;
+    status?: string;
+}
+/** 列出任务真实状态，含 attempt_no 与最新 Claim 摘要（面向模型的文本形式）。 */
+export declare function listTasks(store: KingdomStore, kingdomId: string, input?: ListTasksInput): string;

package/lib/types/core/task.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare const TASK_STATUSES: readonly ["CREATED", "ASSIGNED", "RUNNING", "REVIEW", "DONE", "FAILED"];
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+/**
+ * 唯一合法转移表（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 declare const TASK_TRANSITIONS: Record<TaskStatus, readonly TaskStatus[]>;
+/** Phase 2 终态：不可再转移。 */
+export declare const TERMINAL_TASK_STATUSES: readonly TaskStatus[];
+/** Supervisor 审查决定（冻结三选一）。 */
+export declare const REVIEW_DECISIONS: readonly ["ACCEPT", "REWORK", "FAIL"];
+export type ReviewDecision = (typeof REVIEW_DECISIONS)[number];
+/** ACCEPT/REWORK/FAIL → 目标状态的唯一映射。 */
+export declare const REVIEW_DECISION_TARGET: Record<ReviewDecision, TaskStatus>;
+/** 非法状态转移。抛出即表示调用方试图绕过治理闭环。 */
+export declare class TaskTransitionError extends Error {
+    readonly from: TaskStatus;
+    readonly to: string;
+    constructor(from: TaskStatus, to: string);
+}
+/** 未知状态字符串（库里读到不认识的值时 fail-loud，不静默降级）。 */
+export declare class UnknownTaskStatusError extends Error {
+    constructor(value: string);
+}
+/** 是否为合法状态字符串。 */
+export declare function isTaskStatus(value: string): value is TaskStatus;
+/** 把库里的 TEXT 状态收敛为 TaskStatus；不认识就抛（不猜、不兜底）。 */
+export declare function asTaskStatus(value: string): TaskStatus;
+/** 是否终态。 */
+export declare function isTerminalTaskStatus(status: TaskStatus): boolean;
+/** 纯查询：from → to 是否合法。不抛错。 */
+export declare function canTransition(from: TaskStatus, to: TaskStatus): boolean;
+/**
+ * 状态机唯一入口：校验并返回目标状态，非法即抛。
+ *
+ * 治理纪律：任何写 tasks.status 的代码路径都必须先经过这里
+ * （见 KingdomStore.transitionTask —— 全库唯一的 status UPDATE）。
+ */
+export declare function transition(from: TaskStatus, to: TaskStatus): TaskStatus;

package/lib/types/core/territory.d.ts

@@ -0,0 +1,9 @@
+import { KingdomStore } from './db.js';
+export interface CreateTerritoryInput {
+    kingdomId: string;
+    name: string;
+    workspacePath?: string;
+    summary?: string;
+}
+export declare function createTerritory(store: KingdomStore, input: CreateTerritoryInput): string;
+export declare function listTerritories(store: KingdomStore, kingdomId: string): string;