dsh-kingdom 0.3.1

package/lib/types/gui/contract.d.ts

@@ -0,0 +1,226 @@
+/**
+ * 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 declare const ACTOR_ROLES: readonly ["OWNER", "CHANCELLOR", "SUPERVISOR", "WORKER"];
+export type ActorRole = (typeof ACTOR_ROLES)[number];
+/**
+ * 人物状态（Resolver 的 `state` 维）。
+ *
+ * `absent` 表示该角色没有绑定：GUI 应当**保留组织节点与姓名牌**，只是不渲染人物 Sprite。
+ *
+ * 这份清单是**契约的一部分**：GUI 侧 Visual Resolver 必须逐个处理它们，
+ * 漏掉任何一个都会让人物静默退化成 idle。改动本数组前请同步 GUI。
+ */
+export declare const ACTOR_STATES: readonly ["absent", "idle", "planning", "assigning", "working", "sleeping", "reviewing", "waiting", "confused", "celebrating"];
+export type ActorState = (typeof ACTOR_STATES)[number];
+/**
+ * 角色专属动作（Resolver 的 `activity` 维）。
+ *
+ * 这是**语义**而不是动画名：`review` 表示"正在复核"，
+ * 至于播哪个 clip 由 GUI 的 visual-map 决定。
+ */
+export type ActorActivity = 'plan' | 'read' | 'assign' | 'review' | 'rework' | 'accept' | 'execute' | null;
+/** 命令返回的稳定错误码。GUI 据此决定提示与可用按钮，不解析中文文案。 */
+export type KingdomErrorCode = 'KINGDOM_NOT_INITIALIZED' | 'ROLE_BINDING_MISSING' | 'UNAUTHORIZED_PRINCIPAL' | 'TERRITORY_MISSING' | 'TERRITORY_AMBIGUOUS' | 'TERRITORY_NOT_IN_KINGDOM' | 'TASK_NOT_FOUND' | 'TASK_NOT_IN_KINGDOM' | 'ILLEGAL_TASK_STATE' | 'INVALID_INPUT' | 'INVALID_DECISION' | 'REASON_REQUIRED' | 'WORKER_BINDING_INVALID' | 'EXECUTOR_UNAVAILABLE' | 'WORKER_EXECUTION_FAILED' | 'EXECUTION_NOT_FOUND' | 'ILLEGAL_EXECUTION_STATE';
+/** GUI 可以呈现为按钮的下一步动作。 */
+export type AllowedAction = 'assign' | 'start' | 'review:accept' | 'review:rework' | 'review:fail' | 'execution:pause' | 'execution:resume' | 'execution:abort';
+export interface EventView {
+    seq: number;
+    eventId: string;
+    type: string;
+    actorRole: string | null;
+    actorId: string | null;
+    targetType: string | null;
+    targetId: string | null;
+    payload: Record<string, unknown>;
+    createdAt: string;
+}
+export interface BindingView {
+    bindingId: string;
+    roleType: string;
+    roleName: string;
+    runtimeType: string;
+    sessionId: string | null;
+    createdAt: string;
+}
+export interface TerritoryView {
+    territoryId: string;
+    name: string;
+    workspacePath: string | null;
+    summary: string | null;
+    status: string;
+    createdAt: string;
+}
+/** Worker 的一次自述。**是 Claim，不是完成事实。** */
+export interface ClaimView {
+    resultId: string;
+    attemptNo: number;
+    workerBindingId: string | null;
+    sessionId: string | null;
+    /** Worker 自称的结果，仅供展示与审查，不驱动状态。 */
+    claimedOutcome: string;
+    summary: string | null;
+    artifacts: string[];
+    risks: string[];
+    createdAt: string;
+}
+/** 运行事实。GUI 判断"人物是否在场/在工作/在休息"只看这个。 */
+export interface ExecutionView {
+    executionId: string;
+    taskId: string;
+    attemptNo: number;
+    workerBindingId: string | null;
+    sessionId: string | null;
+    state: string;
+    detail: string | null;
+    startedAt: string;
+    heartbeatAt: string | null;
+    endedAt: string | null;
+    /**
+     * 已登记暂停请求但尚未生效（one-shot 无法在 turn 中途挂起）。
+     * GUI 应显示"准备休息"，**不要**直接播睡觉动画——那会谎报状态。
+     */
+    pausePending: boolean;
+}
+export interface TaskView {
+    taskId: string;
+    territoryId: string;
+    title: string;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    /** 治理事实。注意它 !== 人物是否在工作。 */
+    status: string;
+    assignedBindingId: string | null;
+    /** 最近一次 Claim 的摘要（Claim，不是事实）。 */
+    resultSummary: string | null;
+    attemptCount: number;
+    latestClaim: ClaimView | null;
+    latestExecution: ExecutionView | null;
+    allowedActions: AllowedAction[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** 一个角色此刻应该怎么演。GUI 拿它去查自己的 visual-map。 */
+export interface StageActorView {
+    role: ActorRole;
+    bindingId: string | null;
+    roleName: string | null;
+    state: ActorState;
+    activity: ActorActivity;
+    /** 该状态关联的任务/执行，便于 GUI 做详情联动与人物定位。 */
+    taskId: string | null;
+    executionId: string | null;
+    attemptNo: number | null;
+    /** 状态起始时间（ISO）。GUI 可据此对齐动画进度。 */
+    since: string | null;
+    /**
+     * 一次性动作（如庆祝、派发、规划）。GUI 播完应回落到 `fallbackState`。
+     * 非 transient 的状态是持续循环。
+     */
+    transient: boolean;
+    /** transient 状态的剩余毫秒；GUI 可用它决定是否还要播。 */
+    remainingMs: number | null;
+    /** transient 播完后的稳定状态。 */
+    fallbackState: ActorState;
+    /** 触发本状态的事件序号，便于 GUI 丢弃过期事件。 */
+    sourceSeq: number | null;
+}
+/** 权限诚实度声明。Beta 若未做主体校验，必须让 GUI 能显示这个徽章。 */
+export interface AuthView {
+    /**
+     * `declarative`：只校验"王国中存在该角色绑定"，**不验证调用者就是该角色**。
+     * `session-bound`：额外要求调用方 session 与 binding.session_id 匹配。
+     */
+    mode: 'declarative' | 'session-bound';
+    /**
+     * `local-demo`：本地可信演示权限，不构成真实鉴权。
+     * GUI **必须**在提供派发/复核/返工按钮时显著标注这一点。
+     */
+    trustLevel: 'local-demo' | 'session-verified';
+    note: string;
+}
+export interface SnapshotView {
+    schemaVersion: number;
+    /** = 最大事件序号。GUI 比较它决定是否重绘；也是增量拉取的游标。 */
+    revision: number;
+    /** 服务端生成快照的时刻（ISO），GUI 用它换算 transient 剩余时间。 */
+    generatedAt: string;
+    kingdom: {
+        kingdomId: string;
+        name: string;
+        ownerId: string;
+        ownerName: string;
+        createdAt: string;
+    } | null;
+    auth: AuthView;
+    bindings: BindingView[];
+    territories: TerritoryView[];
+    tasks: TaskView[];
+    liveExecutions: ExecutionView[];
+    /** 每个组织角色此刻的表演语义。 */
+    stage: StageActorView[];
+    recentEvents: EventView[];
+}
+/** 任务详情：验收标准、尝试历史、Claim、Supervisor 决策、关联事件、下一步动作。 */
+export interface TaskDetailView {
+    schemaVersion: number;
+    revision: number;
+    task: TaskView;
+    territory: TerritoryView | null;
+    assignedBinding: BindingView | null;
+    claims: ClaimView[];
+    executions: ExecutionView[];
+    /** Supervisor 的历次裁定（从 events 还原，不存在 task_reviews 表）。 */
+    reviews: {
+        seq: number;
+        decision: string;
+        reason: string | null;
+        reviewerBindingId: string | null;
+        reviewedAttemptNo: number | null;
+        claimedOutcome: string | null;
+        createdAt: string;
+    }[];
+    relatedEvents: EventView[];
+    allowedActions: AllowedAction[];
+}
+/** 所有写命令的统一返回。GUI 只读结构化字段，不解析 `message`。 */
+export interface CommandResultView {
+    ok: boolean;
+    errorCode: KingdomErrorCode | null;
+    /** 给人/模型看的中文说明；GUI 可展示但不得据此判断逻辑。 */
+    message: string;
+    task: TaskView | null;
+    execution: ExecutionView | null;
+    /** 本次命令产生的事件（已带 seq，升序）。 */
+    emittedEvents: EventView[];
+    allowedActions: AllowedAction[];
+    revision: number;
+}
+/** GUI 契约版本。破坏性变更时递增，GUI 应拒绝不认识的版本。 */
+export declare const GUI_SCHEMA_VERSION = 1;
+/** transient 表演动作的默认存活窗口（毫秒）。GUI 轮询 1–2s，足够捕捉。 */
+export declare const TRANSIENT_WINDOW_MS = 3500;

package/lib/types/gui/server.d.ts

@@ -0,0 +1,26 @@
+import type { CommandResultView, SnapshotView, TaskDetailView } from './contract.js';
+import type { EventView } from './contract.js';
+export interface GuiServerHandlers {
+    snapshot(): SnapshotView;
+    taskDetail(taskId: string): TaskDetailView | null;
+    eventsSince(afterSeq: number, limit: number): {
+        revision: number;
+        events: EventView[];
+    };
+    command(name: string, payload: Record<string, unknown>): Promise<CommandResultView>;
+}
+export interface GuiServerOptions {
+    port: number;
+    host?: string;
+    token?: string;
+    allowOrigins?: string[];
+    logger?: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+}
+/**
+ * 启动本地 GUI 通道。
+ * @returns 关闭函数（挂到 ctx.effect，插件卸载/热重载时自动收回端口）。
+ */
+export declare function startGuiServer(handlers: GuiServerHandlers, options: GuiServerOptions): () => void;

package/lib/types/gui/snapshot.d.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh-kingdom — DB 行 → GUI 视图的投影（Phase 3）。
+ *
+ * 全部是**纯函数**：给定 (库状态, now) 就唯一确定输出。
+ * 因此 GUI 轮询即可拿到正确的表演状态，服务端不需要任何定时器或推送状态机。
+ *
+ * 再次强调边界：本文件只产出 `{ role, state, activity }` 这类语义，
+ * 绝不产出贴图、clip、场景文件名——那些是 GUI 的 visual-map 的事。
+ */
+import type { AllowedAction, BindingView, ClaimView, EventView, ExecutionView, StageActorView, TaskDetailView, TaskView, TerritoryView, SnapshotView, AuthView } from './contract.js';
+import { type EventRow, type ExecutionRow, type KingdomStore, type RoleBindingRow, type TaskRow, type TerritoryRow, type WorkerResultRow } from '../core/db.js';
+export declare function toEventView(row: EventRow): EventView;
+export declare function toBindingView(row: RoleBindingRow): BindingView;
+export declare function toTerritoryView(row: TerritoryRow): TerritoryView;
+export declare function toClaimView(row: WorkerResultRow): ClaimView;
+export declare function toExecutionView(row: ExecutionRow): ExecutionView;
+/**
+ * 任务当前允许的下一步动作。
+ *
+ * 这是 GUI 按钮可用性的**唯一**依据——GUI 不应自己从 status 推断，
+ * 否则状态机一改按钮就错。
+ */
+export declare function allowedActionsFor(task: TaskRow, execution: ExecutionRow | null): AllowedAction[];
+export declare function toTaskView(store: KingdomStore, task: TaskRow): TaskView;
+interface StageInput {
+    bindings: RoleBindingRow[];
+    tasks: TaskRow[];
+    executions: ExecutionRow[];
+    events: EventRow[];
+    nowMs: number;
+    transientWindowMs: number;
+}
+/** 计算全部角色此刻的表演语义。 */
+export declare function projectStage(input: StageInput): StageActorView[];
+export interface SnapshotOptions {
+    auth: AuthView;
+    eventLimit?: number;
+    transientWindowMs?: number;
+    /** 注入的"现在"，仅供测试确定性使用。 */
+    nowMs?: number;
+}
+export declare function buildSnapshot(store: KingdomStore, options: SnapshotOptions): SnapshotView;
+export declare function buildTaskDetail(store: KingdomStore, kingdomId: string, taskId: string): TaskDetailView | null;
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * dsh-kingdom — 独立 dsh 插件：会话内初始化/接入本地王国。
+ *
+ * 规范：
+ * - 资源注册必须挂 ctx.effect（热重载/卸载自动清理）。
+ * - 工具 schema 精简：description 短句点明用途，详解放 tool result。
+ *
+ * Phase 1 能力：
+ * - /kingdom init（幂等：无则初始化，有则接入）
+ * - /kingdom status（真实状态）
+ * - 工具：kingdom_status / kingdom_create_territory / kingdom_list_territories /
+ *   kingdom_bind_role / kingdom_list_bindings
+ *
+ * Phase 2 能力（Worker Claim Bridge → 治理闭环）：
+ * - 工具：kingdom_plan_task / kingdom_assign_task / kingdom_start_task /
+ *   kingdom_review_task / kingdom_list_tasks
+ * - Worker 经 one-shot subagent 执行（裁决 2），结果落 worker_results（裁决 4）。
+ *
+ * 治理底线（Phase 1 保持 + Phase 2 强化）：
+ * - **无任何工具能把 Task 直接标 DONE**：DONE 唯一入口是 REVIEW + Supervisor ACCEPT。
+ * - Worker 的结果只是 Claim（→ REVIEW），不是 Fact。
+ * - 无任意 SQL 通道暴露给 Agent。
+ */
+import type { Context } from 'cordis';
+import z from 'schemastery';
+export declare const name = "dsh-kingdom";
+export declare const inject: string[];
+export interface Config {
+    kingdomName: string;
+    ownerName: string;
+    workerProvider: string;
+    guiPort: number;
+    guiToken: string;
+    guiAllowOrigins: string[];
+    authMode: 'declarative' | 'session-bound';
+}
+export declare const Config: z<Schemastery.ObjectS<{
+    kingdomName: z<string, string>;
+    ownerName: z<string, string>;
+    /** Worker 执行用的 subagent provider（dsh base bundle 默认注册 spawn / fork）。 */
+    workerProvider: z<string, string>;
+    /**
+     * 本地 GUI 通道端口。**默认 0 = 关闭** —— 不在用户不知情时打开监听端口。
+     * 设为非零值即启用，只绑定 127.0.0.1。
+     */
+    guiPort: z<number, number>;
+    /** 可选 bearer token；设置后 GUI 所有请求都要带 Authorization 头。 */
+    guiToken: z<string, string>;
+    /** CORS 允许的 Origin 列表；默认放开（服务只绑本机回环）。 */
+    guiAllowOrigins: z<string[], string[]>;
+    /**
+     * 角色鉴权强度。
+     * `declarative`（默认，Phase 1/2 延续）只校验"王国中存在该角色绑定"，
+     * **不验证调用者就是该角色** —— snapshot 会如实报 `trustLevel: local-demo`。
+     * `session-bound` 额外要求调用方 session 与 binding.session_id 一致。
+     */
+    authMode: z<"declarative" | "session-bound", "declarative" | "session-bound">;
+}>, Schemastery.ObjectT<{
+    kingdomName: z<string, string>;
+    ownerName: z<string, string>;
+    /** Worker 执行用的 subagent provider（dsh base bundle 默认注册 spawn / fork）。 */
+    workerProvider: z<string, string>;
+    /**
+     * 本地 GUI 通道端口。**默认 0 = 关闭** —— 不在用户不知情时打开监听端口。
+     * 设为非零值即启用，只绑定 127.0.0.1。
+     */
+    guiPort: z<number, number>;
+    /** 可选 bearer token；设置后 GUI 所有请求都要带 Authorization 头。 */
+    guiToken: z<string, string>;
+    /** CORS 允许的 Origin 列表；默认放开（服务只绑本机回环）。 */
+    guiAllowOrigins: z<string[], string[]>;
+    /**
+     * 角色鉴权强度。
+     * `declarative`（默认，Phase 1/2 延续）只校验"王国中存在该角色绑定"，
+     * **不验证调用者就是该角色** —— snapshot 会如实报 `trustLevel: local-demo`。
+     * `session-bound` 额外要求调用方 session 与 binding.session_id 一致。
+     */
+    authMode: z<"declarative" | "session-bound", "declarative" | "session-bound">;
+}>>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/paths.d.ts

@@ -0,0 +1,6 @@
+/** 解析 dsh 主目录：DSH_HOME 环境变量优先，否则 ~/.dsh。 */
+export declare function resolveDshHome(): string;
+/** kingdom 数据根目录：<dshHome>/kingdom */
+export declare function kingdomRoot(): string;
+/** kingdom 数据库文件：<dshHome>/kingdom/kingdom.db */
+export declare function kingdomDbPath(): string;

package/lib/types/worker/dsh-subagent.d.ts

@@ -0,0 +1,79 @@
+/**
+ * dsh-kingdom — DshSubagentExecutor：用 dsh one-shot subagent 执行 Worker（裁决 2）。
+ *
+ * 裁决 2 冻结的形状：
+ * - Worker 用 `ctx.subagents.start(provider, { label, prompt, outputSchema })` **one-shot 独立执行**；
+ * - **不**采用常驻 `ctx.agents.create`；
+ * - 每次执行都是新的 execution/session（REWORK 也一样，裁决 5）；
+ * - Structured Worker Result 由 subagent 的 `outputSchema` 约束，
+ *   宿主（本类）接收后交给 Task Core 落 worker_results。
+ *
+ * 这也是为什么 `kingdom_report_result` **不是**独立工具：Worker 是 one-shot subagent，
+ * 它没有机会自己调工具改 Task 状态 —— 结果只能经宿主这一条路回来。
+ *
+ * ## 为什么这里对 ctx.subagents 用结构化局部类型
+ *
+ * 本插件是独立分发的 tgz，peer 只声明 5 条（见 README）。为了不新增第 6 条 peer、
+ * 也不让编译产物 .d.ts 泄漏 subagent 类型，这里按 dsh 已发布的接口**结构化**地
+ * 声明所需最小面，而不 import `@deepseek-ai/dsh-subagent`。
+ * 对应 checkout 定义（0.1.0/0.2.0 基线一致）：
+ * - `SubagentRuntime.start(name, request)` — packages/subagent/subagent/src/index.ts:414
+ * - `SubagentStartRequest{label,prompt,parent,signal,outputSchema}` — .../src/types.ts:100
+ * - `SubagentRun{id,result,dispose}` / `SubagentResult{output,structured,stopReason}` — .../src/types.ts:219,249
+ */
+import { type WorkerContext, type WorkerExecutionOutcome, type WorkerExecutor } from './executor.js';
+import type { TaskRow } from '../core/db.js';
+/** dsh `SubagentResult` 的最小结构面。 */
+interface SubagentResultLike {
+    readonly structured?: unknown;
+    readonly stopReason: string;
+}
+/** dsh `SubagentRun` 的最小结构面。 */
+interface SubagentRunLike {
+    readonly id: string;
+    readonly result: Promise<SubagentResultLike>;
+    dispose(): Promise<void>;
+}
+/** dsh `SubagentRuntime` 的最小结构面。 */
+export interface SubagentsLike {
+    start(name: string, request: {
+        label?: string;
+        prompt: {
+            type: 'text';
+            text: string;
+        }[];
+        parent: unknown;
+        signal: AbortSignal;
+        outputSchema?: unknown;
+    }): Promise<SubagentRunLike>;
+    getProvider(name: string): unknown;
+    list(): string[];
+}
+/** 构造 DshSubagentExecutor 所需的一次性运行期入参。 */
+export interface DshSubagentExecutorOptions {
+    /** `ctx.get('subagents')` 拿到的 subagent 注册表。 */
+    subagents: SubagentsLike;
+    /** provider 名（dsh base bundle 默认注册 `spawn` / `fork`）。 */
+    provider: string;
+    /**
+     * 发起委派的父 Agent（来自工具执行上下文 `exec.agent`）。
+     * in-process provider 从它派生 workspace / 血缘 / 委派深度。
+     */
+    parent: unknown;
+    /** 调用方的取消信号（`exec.signal`）。 */
+    signal: AbortSignal;
+}
+/**
+ * 薄封装：把一次 Worker 执行落到一个 one-shot subagent run 上。
+ *
+ * 失败一律收敛成 `executor-failure`，**从不抛异常给 Task Core**
+ * —— 让状态机只面对两种确定结局（result / executor-failure），
+ * 而不是异常与返回值两条并行的控制流。
+ */
+export declare class DshSubagentExecutor implements WorkerExecutor {
+    readonly kind: string;
+    private readonly options;
+    constructor(options: DshSubagentExecutorOptions);
+    execute(task: TaskRow, context: WorkerContext): Promise<WorkerExecutionOutcome>;
+}
+export {};

package/lib/types/worker/executor.d.ts

@@ -0,0 +1,121 @@
+/**
+ * dsh-kingdom — WorkerExecutor 接口（Phase 2，Owner 裁决 2）。
+ *
+ * 裁决 2 的形状：**Task Core 只依赖本接口，绝不直接 import subagents。**
+ * 换执行方式（one-shot subagent → 别的 runtime）不碰状态机。
+ * Worker ≠ Subagent Session：Worker 是组织角色（role_binding），
+ * subagent execution 只是它这一轮的执行载体。
+ *
+ * 本文件**零 dsh 依赖**：只有类型和纯函数，因此 Task Core 与自测都不需要活的 DSH。
+ */
+import type { TaskRow } from '../core/db.js';
+/**
+ * Worker 交回的结构化结果（受 subagent outputSchema 约束）。
+ *
+ * **这是 Claim，不是 Fact。** outcome 是 Worker 的自述，
+ * 不参与任何自动状态决策：即使 outcome === 'FAILED'，
+ * Task 也只推到 REVIEW，等 Supervisor 裁定（裁决 6）。
+ */
+export interface StructuredResult {
+    /** Worker 自称的结果。 */
+    outcome: 'COMPLETED' | 'FAILED' | 'BLOCKED';
+    /** 一段可供 Supervisor 审查的自述摘要。 */
+    summary: string;
+    /** 产出物（文件路径 / 制品标识），可选。 */
+    artifacts?: string[];
+    /** Worker 自述的风险与遗留问题，可选。 */
+    risks?: string[];
+}
+/** 传给 Worker 的这一轮上下文（裁决 5：REWORK 时带上一轮摘要 + 返工理由）。 */
+export interface WorkerContext {
+    /** 原始 Task。 */
+    task: TaskRow;
+    /** 验收标准（Task 的 acceptance_criteria）。 */
+    acceptanceCriteria: string | null;
+    /** 第几次尝试，从 1 起。 */
+    attemptNo: number;
+    /** 上一轮 Worker Claim 的摘要（仅 REWORK 时存在）。 */
+    prevResultSummary?: string;
+    /** Supervisor 的 REWORK 理由（仅 REWORK 时存在）。 */
+    reworkReason?: string;
+}
+/**
+ * 一次 Worker 执行的结果，只有两种：
+ *
+ * - `result`：subagent 正常返回**合法结构化结果** → Task 推到 REVIEW（Claim 到达）。
+ * - `executor-failure`：启动失败 / 异常退出 / 无合法 outputSchema 输出
+ *   → Core 直接 RUNNING → FAILED（裁决 6：**宿主观察到的运行事实**，不是相信 Worker 自述）。
+ *
+ * 注意这两者的区别就是 Phase 2 的治理核心：Worker 说自己失败了是 Claim（走 REVIEW），
+ * 宿主看见 executor 没跑出合法结果是 Fact（直接 FAILED）。
+ */
+export type WorkerExecutionOutcome = {
+    kind: 'result';
+    result: StructuredResult;
+    sessionId: string | null;
+} | {
+    kind: 'executor-failure';
+    reason: string;
+    sessionId: string | null;
+};
+/** 薄执行封装。Task Core 只认这一个接口。 */
+export interface WorkerExecutor {
+    /** 供事件/诊断使用的执行器标识（如 `dsh-subagent:spawn`）。 */
+    readonly kind: string;
+    execute(task: TaskRow, ctx: WorkerContext): Promise<WorkerExecutionOutcome>;
+}
+/**
+ * 约束 Worker 结构化输出的 JSON Schema。
+ *
+ * 必须落在 dsh 强制的 schema 子集内
+ * （见 checkout `packages/core/tools/src/json-schema.ts`）：
+ * - 根必须是 object（assertObjectJsonSchema）；
+ * - `enum` 只允许挂在**已声明 scalar `type`** 的节点上
+ *   —— 裸 `{ enum: [...] }` 会被判为 `.enum requires type or oneOf` 而拒绝，
+ *   所以 outcome 显式写了 `type: 'string'`。
+ */
+export declare const WORKER_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["outcome", "summary"];
+    readonly properties: {
+        readonly outcome: {
+            readonly type: "string";
+            readonly enum: readonly ["COMPLETED", "FAILED", "BLOCKED"];
+            readonly description: "COMPLETED=你认为已完成；FAILED=你认为做不成；BLOCKED=被外部阻塞。这是你的声明，最终由 Supervisor 裁定。";
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly description: "给 Supervisor 审查用的自述摘要：做了什么、结果如何、是否满足验收标准。";
+        };
+        readonly artifacts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "产出物列表（文件路径或制品标识）。";
+        };
+        readonly risks: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "风险与遗留问题。";
+        };
+    };
+};
+/**
+ * 把 subagent 交回的 `structured` 收敛成 StructuredResult。
+ *
+ * provider 已按 outputSchema 校验过，这里是**宿主侧的第二道防御**：
+ * 形状不合法就返回 null，调用方据此判定 executor-failure（裁决 6）。
+ * 不猜、不补默认值 —— 一个形状不对的 Claim 不是 Claim。
+ */
+export declare function parseStructuredResult(value: unknown): StructuredResult | null;
+/**
+ * 构造这一轮 Worker 的 prompt。
+ *
+ * 裁决 5：REWORK 轮次必须注入「原 Task + Acceptance Criteria +
+ * 上一轮 Result 摘要 + Supervisor REWORK reason」。
+ * one-shot subagent 不继承父会话上下文，所以 prompt 必须自包含。
+ */
+export declare function buildWorkerPrompt(context: WorkerContext): string;