@william2000/dsh-nova-ui-task-board 0.2.1 → 0.3.1

package/lib/types/host-ledger.d.ts

@@ -1,67 +1,17 @@
-/**
- * Host 权威账本（DSH-REQ-001 §8 架构 / §9.1 / §17 可靠性）。
- *
- * 「Host 权威、浏览器只是异步视图」的数据底座：所有任务状态持久化到
- * `$DSH_HOME/nova-ui/task-board/ledger-v2.json`（0600，原子写），保证重启不丢、
- * 并发一致、损坏可隔离。T003（协议）/T005（执行）/T006（调度）等在此之上工作。
- *
- * 可靠性机制（§17 / §19-7 数据部分）：
- * - **原子写**：临时文件 + fsync + 原子 rename + 目录 fsync；任何失败清理临时
- *   文件并重新抛出，绝不产生半写文件；
- * - **损坏隔离**：schema 不兼容/不可解析的账本 rename 为 `ledger-v2.json.corrupt-*`
- *   （保留原字节）并以空账本重建，不崩溃；
- * - **单写者锁**：`ledger-v2.lock`（0600，`wx` 排他创建）记录 PID + token +
- *   进程启动时间探测；PID 复用通过启动时间不匹配识别为陈旧锁并接管（防误判），
- *   僵尸/死亡进程（Z/X）不阻塞启动；
- * - **幂等缓存**：`recentRequests`（最近 256 条 requestId→SHA-256 指纹）随账本
- *   原子持久化，Host 重启后浏览器重试仍安全（§11.3）；
- * - **v1 迁移**：`importSource` 按 sourceId 一次性导入、按 id 合并，导入 marker
- *   随原子落账持久化（Host 确认后浏览器才清除 v1 原值，见 core/migrate.ts）。
- *
- * 串行性：本类全部方法为同步实现（无 await），单进程内天然串行；跨进程互斥
- * 由锁保证。`revision` 每次原子落账严格 +1（scheduler 心跳类补丁除外，见
- * `setScheduler`）。
- */
 import type { AutomationRule, LedgerDocument, LedgerScheduler, LedgerState, SchedulerSnapshot, TaskRecord } from './core/model.ts';
-/**
- * 尽力而为的单字母进程状态（'R','S','D','Z',...），平台不支持时返回 undefined。
- * Linux 直接读 /proc（无子进程）；其他 POSIX 用 `ps -o stat=`；Windows 无僵尸
- * 态，返回 undefined（此时 kill(0) 探测为唯一权威）。
- */
 export declare function processState(pid: number): string | undefined;
-/** PID 是否存活（僵尸/死亡态视为不存活）。 */
 export declare function processIsAlive(pid: number): boolean;
-/**
- * 尽力而为的进程启动时间（Unix epoch ms），用于证明锁记录里的 PID 是否真的是
- * 之前那个进程（PID 复用会被识别为陈旧锁而不是永久阻塞启动）。平台探测不可用
- * 时返回 undefined，调用方 fail closed。
- */
 export declare function processStartTimeMs(pid: number): number | undefined;
-/** 记录的启动时间是否证明记录的 PID 已是另一个进程（PID 复用探测核心）。 */
 export declare function startTimeMismatch(recorded: number, actual: number, exact: boolean): boolean;
-/**
- * 进程探测面（§17 可测试性：Host 编排用结构面注入 fake）。生产默认用真实
- * 平台探测；测试可注入假实现来覆盖 PID 复用接管等分支（真实探测在部分
- * 沙箱/系统上不可用——如 macOS 限制 ps——会 fail closed 而非误判）。
- */
 export interface ProcessProbes {
     isAlive(pid: number): boolean;
-    /** 进程启动时间（Unix epoch ms）；平台探测不可用时返回 undefined。 */
     startTimeMs(pid: number): number | undefined;
-    /** 本进程启动时间（带缓存）。 */
     ownStartTimeMs(): number | undefined;
 }
-/**
- * Host 权威账本。构造即获取单写者锁并加载/恢复账本；进程内所有写入经
- * `applyRequest`/`importSource`/`mutate`/`setScheduler` 串行原子落账。
- */
 export declare class HostLedger {
     private readonly now;
-    /** 账本文件绝对路径。 */
     readonly file: string;
-    /** 锁文件绝对路径。 */
     readonly lockFile: string;
-    /** 账本目录。 */
     readonly dir: string;
     private document;
     private readonly listeners;
@@ -69,78 +19,24 @@ export declare class HostLedger {
     private readonly lockToken;
     private lockFd;
     private readonly probes;
-    /**
-     * @param dir - 账本目录（默认 `$DSH_HOME/nova-ui/task-board/`，见 AGENTS.md D2）。
-     * @param now - 时间源（测试可注入）。
-     * @param probes - 进程探测面（默认真实探测；测试可注入 fake，见 §17 可测试性）。
-     */
     constructor(dir?: string, now?: () => number, probes?: ProcessProbes);
-    /** revision + scheduler（不克隆任务），供 SSE 事件帧使用。 */
     summary(): {
         revision: number;
         scheduler: SchedulerSnapshot;
     };
-    /** 全量状态快照（任务/规则深拷贝，调用方修改不影响账本）。 */
     state(): LedgerState;
-    /**
-     * 只读任务数组（不克隆，O(1)）。仅供服务层扫描/计数（如 power 快照的
-     * runningSessions/armedSchedules）；**绝不可修改**——任何变更必须走
-     * `applyRequest`/`mutate` 的原子落账路径。
-     */
     peekTasks(): readonly TaskRecord[];
-    /** 只读自动化规则数组（不克隆；变更必须走 applyRequest/mutate 原子落账）。 */
     peekAutomationRules(): readonly AutomationRule[];
-    /** 订阅账本变更（每次原子落账后触发）。 */
     subscribe(listener: () => void): () => void;
-    /** 释放锁（仅当锁仍属本实例时删除锁文件，避免误删外部替换的锁）。 */
     dispose(): void;
-    /**
-     * 幂等 action 应用（§11.3）。调用方（T003 协议层）提供序列化的 action（仅
-     * 用于 SHA-256 指纹）与变更闭包；闭包返回 true 表示文档有实际变更。
-     *
-     * - 重复 requestId + 相同指纹 → 直接返回当前 state（不重新应用、不 bump）；
-     * - 同 requestId + 不同动作 → 抛错（`request id was reused with a different action`）；
-     * - 首次请求 → 指纹先行入缓存，随后应用；变更闭包抛错则回滚缓存条目；
-     * - 成功且 changed → 原子落账（revision+1），指纹随账本一并持久化——
-     *   Host 重启后浏览器重试仍安全。
-     *
-     * @param requestId - 浏览器侧 uuid。
-     * @param action - 序列化 action（指纹源；必须可 JSON 序列化）。
-     * @param apply - 变更闭包，就地修改文档；返回 true 表示发生变更（需落账）。
-     */
     applyRequest(requestId: string, action: unknown, apply: (doc: LedgerDocument) => boolean): LedgerState;
-    /**
-     * v1 迁移导入（§11.2 `import` / §9.5）：按 sourceId 一次性导入、按 id 合并、
-     * 写入 importedSources marker（原子落账确认后才写入）。重复 sourceId 幂等
-     * no-op（不落账不 bump）。浏览器以成功响应 + 记住 ledgerId 作为确认凭证
-     * （T003/T004 接线；marker 不进 state/summary，见 `summary`）。
-     */
     importSource(requestId: string, sourceId: string, tasks: readonly TaskRecord[]): LedgerState;
-    /**
-     * 通用原子变更（Host 编排用，T005/T006 的 runner/scheduler 也走这里）。
-     * `apply` 返回 true 才落账（revision+1）；返回 false 保持 revision 不变。
-     */
     mutate(apply: (doc: LedgerDocument) => boolean): LedgerState;
-    /**
-     * 更新 scheduler 补丁（心跳 lastTickAt、错误可见性等，§9.1）。
-     * 不 bump revision（避免 30s 心跳驱动客户端全量重拉）；无实际变更不写盘。
-     */
     setScheduler(patch: Partial<LedgerScheduler>): void;
     private syncRecentRequests;
-    /**
-     * 原子落账：临时文件 + fsync + 原子 rename + 目录 fsync（0600）。
-     * 任一步失败清理临时文件并重新抛出——绝不产生半写文件。
-     */
     private commit;
-    /** 加载账本；损坏/schema 不兼容 → 隔离原文件并以空账本重建（§17 损坏隔离）。 */
     private load;
-    /** 损坏隔离：原文件 rename 为 `ledger-v2.json.corrupt-<ts>-<pid>-<uuid>`，原字节保留。 */
     private quarantine;
     private notify;
-    /**
-     * 获取单写者锁：`wx` 排他创建（已存在则 EEXIST 走锁主判定）。
-     * 锁记录 PID + token + 启动时间探测；PID 复用（启动时间不匹配）识别为陈旧锁
-     * 并接管；锁不可读时 fail closed（提示人工清理）。
-     */
     private acquireLock;
 }

package/lib/types/host-routes.d.ts

@@ -1,46 +1,14 @@
-/**
- * 路由层（DSH-REQ-001 §11.1 三端点 + §16 安全栅栏）。
- *
- * 端点（同源，前缀 `/api/nova-task-board`）：
- * - `GET  /api/nova-task-board/state`   → 全量快照 `{schemaVersion, revision,
- *   tasks, scheduler, power, automationRules}`；
- * - `POST /api/nova-task-board/action`  → 幂等信封 `{requestId, action}`，返回
- *   新 snapshot；
- * - `GET  /api/nova-task-board/events`  → SSE 推送 `{revision, scheduler,
- *   power}`（15s 心跳注释帧），revision 变化时客户端重拉 state；
- * - `POST /api/nova-task-board/webhooks/github` → GitHub `issues` 事件接收
- *   （T010 §14.1）：HMAC-SHA256 签名校验（`X-Hub-Signature-256`，密钥来自
- *   环境变量，不落配置）；未配置密钥 → 503；签名不匹配 → 401。该端点不走
- *   浏览器同源栅栏（GitHub 无法携带浏览器信号），HMAC 即权威边界。
- *
- * 安全栅栏（§16.1/16.2/16.3）：
- * - 浏览器同源标记（sec-fetch-site/Origin）为触发器而非权威校验——裸命令行
- *   请求（curl 无任何浏览器信号）直接 403；权威边界是回环 socket + Host +
- *   origin 等价校验（loopback.ts + isTrustedTaskBoardRequest）；
- * - 同机认证反代必须白名单（trustedProxyHosts 规范化 authority）+ 服务端注入
- *   token（`x-dsh-task-board-proxy-token`，timingSafeEqual 比较）；
- * - POST 必须 application/json（否则 415）；普通 action ≤ 64 KiB、import /
- *   propose-batch / start-split ≤ 2 MiB（超限 413）；非法信封/未知 action → 400
- *   invalid-action；状态机守卫失败 → 400 + 错误信息。
- */
 import type { IncomingMessage } from 'node:http';
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { TaskBoardHostService } from './host-service.ts';
-/** 普通 action 载荷上限（§11.1）。 */
 export declare const ACTION_LIMIT: number;
-/** import（批量候选同限）载荷上限（§11.1）。 */
 export declare const IMPORT_LIMIT: number;
-/** SSE 心跳间隔（§17 性能：SSE 心跳 15s）。 */
 export declare const HEARTBEAT_MS = 15000;
-/** 同机认证反代在自身认证后替换注入的服务端 token 头（§16.1）。 */
 export declare const TASK_BOARD_PROXY_TOKEN_HEADER = "x-dsh-task-board-proxy-token";
-/** GitHub Webhook 签名头（HMAC-SHA256，`sha256=<hex>`，§14.1）。 */
 export declare const GITHUB_SIGNATURE_HEADER = "x-hub-signature-256";
-/** 路由访问面：默认仅回环 + 浏览器同源标记；反代须白名单 + token。 */
 export interface TaskBoardRouteAccess {
     trustedProxyHosts?: readonly string[];
     proxyToken?: string;
-    /** GitHub Webhook HMAC 密钥（env 解析，不落配置；缺省 = Webhook 端点不可用）。 */
     webhookSecret?: string;
 }
 interface ResolvedRouteAccess {
@@ -48,18 +16,8 @@ interface ResolvedRouteAccess {
     proxyToken?: string;
     webhookSecret?: string;
 }
-/** 解析访问面并校验白名单条目的规范化形态（配置错误直接 throw，插件加载失败）。 */
 export declare function resolveAccess(access: TaskBoardRouteAccess): ResolvedRouteAccess;
-/**
- * GitHub Webhook 签名校验（§14.1）：`X-Hub-Signature-256: sha256=<hex>`，
- * 对原始请求体做 HMAC-SHA256 并恒定时间比较。签名头缺失/畸形/不匹配 → false。
- */
 export declare function verifyGithubSignature(rawBody: string, signature: string | string[] | undefined, secret: string): boolean;
-/**
- * 请求级信任判定：浏览器同源标记 + （回环请求 | 白名单反代 + token）。
- * 回环判定包含 socket 地址、Host 头与 origin 等价校验（loopback.ts）。
- */
 export declare function isTrustedTaskBoardRequest(req: IncomingMessage, access: ResolvedRouteAccess): boolean;
-/** 组装三个端点路由（宿主的 webServer.register 对重复 (kind, path) 直接 throw，勿重复注册）。 */
 export declare function makeTaskBoardRoutes(service: TaskBoardHostService, access?: TaskBoardRouteAccess): WebRoute[];
 export {};

package/lib/types/host-runner.d.ts

@@ -1,43 +1,13 @@
-/**
- * 真实执行与结算（DSH-REQ-001 §13，T005）。
- *
- * HostExecutionRunner 是「点击执行 → 独立 DSH 会话 → 按 turn 结算」的执行驱动：
- *
- * - **launch（§13.2）**：fail-closed 钉住目标——工作区必须存在于 workspace.list、
- *   agent 预设必须存在且未损坏，任一失败直接抛错（服务层结算 failed，绝不发送
- *   任务 Prompt）；随后创建独立会话（sessions.create，携带钉住的 workspaceId/
- *   agentPreset）→ rename 为任务标题（**可失败但仅装饰**，§13.2）→ 钉住权限经
- *   `/permission <id>` 命令应用（被拒/未匹配 → 失败）→ `sessions.prompt(mode:
- *   'queue', text = prompt || title)`。会话创建后的失败包装为
- *   `SessionLaunchError`（携带 sessionId，服务层先回填再结算，保留跳转线索）。
- * - **listRunning（§13.3）**：轮询会话列表（会话列表 RPC 失败 → known:false，
- *   服务层据此标记 sessionStateKnown=false）。
- * - **inspect（§13.3）**：单条执行的结算判定——会话消失 → cancelled；仍在运行
- *   → pending；已结束 → 翻页读历史，取时间 ≥ startedAt 的首条 `turn/end`
- *   判定：`reason.kind === 'error'` → failed，否则 → succeeded。
- *
- * 依赖面（§17 可测试性）：本类只依赖 `ctx.apiProxy` 的窄子集（ExecutionApi）与
- * 命令调度器（ExecutionCommandDispatcher，`/permission` 走宿主 commands
- * 注册表、不经模型），测试注入 fake 即可脱离宿主单测；生产接线在 index.ts。
- *
- * 执行隔离（§16.4）：任务 Prompt 只作为发给 agent 的数据；权限只能经
- * `/permission` 命令应用，Prompt 不能提权。
- */
 import type { HistoryEntry, PromptContentPart, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import type { TaskRecord } from './core/model.ts';
-/** `/permission <id>` 命令的超时（对齐参考实现 30s）。 */
 export declare const PERMISSION_COMMAND_TIMEOUT_MS = 30000;
-/** inspect 历史翻页上限（对齐参考实现）。 */
 export declare const MAX_HISTORY_PAGES = 100;
-/** inspect 每页事件数（对齐参考实现）。 */
 export declare const HISTORY_PAGE_SIZE = 100;
-/** 会话列表行（inspect 所需的最小面；SDK SessionSummary 是其超集）。 */
 export interface ExecutionSessionRow {
     sessionId: string;
     running: boolean;
 }
-/** 5s 轮询的会话列表状态（§13.3）：RPC 失败时 known:false（服务层据此降级）。 */
 export type ExecutionSessionState = {
     known: true;
     count: number;
@@ -45,20 +15,13 @@ export type ExecutionSessionState = {
 } | {
     known: false;
 };
-/** 单条执行的结算判定（§13.3）。 */
 export type ExecutionOutcome = 'pending' | 'cancelled' | 'failed' | 'succeeded';
 export interface ExecutionInspection {
     outcome: ExecutionOutcome;
     error?: string;
-    /** 本次执行（startedAt 之后）最近的 assistant 消息文本（B5：Host 侧摘取摘要源）。 */
     lastAssistantText?: string;
 }
-/** `/permission <id>` 命令调度面（index.ts 接线到宿主 ctx.commands，见 §16.4）。 */
 export interface ExecutionCommandDispatcher {
-    /**
-     * 在会话上执行一条斜杠命令（不经模型）。undefined = 未被承认（命令名不匹配/
-     * 语法未解析）；kind:'error' = 被拒/未匹配。
-     */
     execute(sessionId: string, line: string, signal: AbortSignal): Promise<{
         kind: 'success';
         text?: string;
@@ -67,10 +30,6 @@ export interface ExecutionCommandDispatcher {
         text: string;
     } | undefined>;
 }
-/**
- * HostExecutionRunner 依赖的 API 窄面（ctx.apiProxy 的结构子集）。只声明
- * launch/inspect 用到的域方法；生产传完整 ApiProxy（结构兼容），测试传 fake。
- */
 export interface ExecutionApi {
     workspace: {
         list(request: RpcRequest<{}>): Promise<RpcResponse<{
@@ -127,62 +86,18 @@ export interface ExecutionApi {
         }>>;
     };
 }
-/** 会话创建后的启动失败：仍标识会话（服务层先回填 sessionId 再结算 failed）。 */
 export declare class SessionLaunchError extends Error {
     readonly sessionId: string;
     constructor(sessionId: string, cause: unknown);
 }
-/** 会话 transcript 全文读取上限（T012/B8：拆分会话结果解析；防超大会话内存放大）。 */
 export declare const TRANSCRIPT_TEXT_LIMIT = 200000;
-/**
- * 真实执行与结算驱动（§13.2/§13.3）。无状态、无计时器——轮询调度由
- * TaskBoardHostService 持有（5s 间隔）；本类只做单次 launch/inspect。
- */
 export declare class HostExecutionRunner {
     private readonly api;
     private readonly commands;
-    /** @param api - apiProxy 窄面（workspace/agentPresets/sessions 的读写子集）。 */
     constructor(api: ExecutionApi, commands: ExecutionCommandDispatcher | undefined);
-    /**
-     * 启动一次执行（§13.2 流程）：
-     * 1. fail-closed 校验钉住目标（工作区存在、预设存在且未损坏）——任一失败抛
-     *    错，调用方结算 failed，**不发送任务 Prompt**；
-     * 2. `sessions.create` 创建独立会话（携带钉住的 workspaceId/agentPreset）；
-     * 3. rename 为任务标题（可失败但仅装饰）；权限经 `/permission` 命令应用
-     *    （被拒/未匹配 → 失败）；
-     * 4. `sessions.prompt(mode:'queue', text = prompt || title)`。
-     *
-     * 会话创建之后的任何失败抛 `SessionLaunchError`（携带 sessionId）。
-     * @returns 创建的会话 id。
-     */
     launch(task: TaskRecord): Promise<string>;
-    /**
-     * 轮询会话列表（§13.3，5s 一次由服务层调度）。RPC 失败/不可用 → known:false
-     * （服务层据此把 sessionStateKnown 置 false，不据此结算）。
-     */
     listRunning(): Promise<ExecutionSessionState>;
-    /**
-     * 单条执行的结算判定（§13.3）：
-     * - 会话不在列表中 → cancelled（`execution session no longer exists`）；
-     * - 会话仍在运行 → pending；
-     * - 已结束 → 翻页读历史直到越过 startedAt 边界，取时间 ≥ startedAt 的首条
-     *   `turn/end`：reason.kind==='error' → failed，否则 → succeeded；边界内无
-     *   turn/end（如 prompt 从未被消费）→ pending（保持观察）。
-     * @param sessions - 本次轮询已取的会话列表（避免 1 + E 次 list RPC，对齐参考
-     *   实现）；缺省时自行拉取。
-     */
     inspect(sessionId: string, startedAt: number, sessions?: readonly ExecutionSessionRow[]): Promise<ExecutionInspection>;
-    /**
-     * 停止底层会话（§13.3 用户取消执行）：尽力而为——RPC 失败/被拒/会话不存在
-     * 都只记日志，不抛给控制面（账本侧 cancelled 结算已权威，本调用只是避免
-     * 孤儿 agent 继续空转/烧额度）。
-     */
     cancelSession(sessionId: string): Promise<void>;
-    /**
-     * 读取会话 transcript 全文（T012/B8：拆分会话结果解析用）。翻页读取历史事件，
-     * 拼接全部 assistant 消息文本（顺序拼接、换行分隔；总长封顶
-     * TRANSCRIPT_TEXT_LIMIT）。会话不存在/历史不可读 → undefined（调用方按失败
-     * 处理）。拆分会话是独立专用会话，全文即拆分结果（无需按 startedAt 截取）。
-     */
     readTranscriptText(sessionId: string): Promise<string | undefined>;
 }

package/lib/types/host-service.d.ts

@@ -1,130 +1,34 @@
-/**
- * 任务看板协议服务层（DSH-REQ-001 §8 架构「Host（控制面）」）。
- *
- * T003 交付控制面的串行应用骨架：浏览器提交 `{requestId, action}` → 幂等判定
- * （复用 T002 HostLedger 的 applyRequest + recentRequests 持久化）→ 状态机
- * 守卫（core/transitions.ts）→ 原子落账（revision+1）→ 返回全量 snapshot。
- * T005 接入真实执行（§13）：`run/rerun` action 经状态机开执行记录后由
- * HostExecutionRunner 启动独立 DSH 会话；5s 轮询会话列表按 turn 结算
- * （§13.3）；Host 重启后带 sessionId 的 running 执行由轮询继续观察结算。
- * T006 接入 cron 周期定时（§9.4/§13.1）：30s tick 扫描到期任务并触发执行
- * （浏览器关闭也生效）——启动/恢复首个 tick 跳过错过的触发点（不补跑）、
- * 到期且 enabled → 复用 T005 的 launch 入口开启执行、同任务 running 中到期
- * 只滚动到下一匹配点不并发；`set-schedule` action（§11.2）设定/修改/关闭
- * cron（nextRunAt/lastTriggeredAt 为 Host 独占字段）。
- * T007 接入一次性计划（§9.4/§11.2 set-one-shot/§13.5）：同一 30s tick 同时
- * 扫描 one-shot——`runAt ≤ now && firedAt 缺省` 即触发一次并写 firedAt（触发
- * 即消费，绝不重复）；触发时任务 running → 不并发不排队、本次仍标记消费；
- * 错过（停机/睡眠/长暂停，恢复首 tick）→ 跳过不补跑、写 firedAt 展示「已过期
- * /已跳过」；`set-one-shot` 设定/修改/清除（runAt 缺省或 0 = 取消），与 cron
- * 互斥（D6）。
- * T009 接入列内排序与跨列拖拽（§9.2/§10.2/§11.2/§12.10）：`reorder` 经状态机
- * 重算列内 order（同列唯一、整列重编号；status 须与当前状态一致防竞态；可携带
- * project/tags 归属变更原子落账）、`move.order` 可选落位（缺省追加目标列末尾，
- * done/failed 拖回 backlog/todo 为重开不触发执行）。分组视图模式由浏览器端持有，
- * Host 不感知（§12.10）。
- * T010 接入自动化收集与上下文闭环（§9.5/§14，P3）：
- * - 自动化规则（§9.5 automation_rules）：`upsert-automation`/`delete-automation`
- *   落账；30s tick 与任务 schedule 同轮扫描规则 cron——到期滚动
- *   （applyCollectorRoll）后异步执行收集（收藏收件箱文件 / GitHub API 轮询，
- *   host-automation.ts），恢复期首 tick 跳过（applySkipMissedAutomationRules，
- *   错过不补跑）；`run-automation` 手动触发一次收集（只滚 lastTriggeredAt，
- *   不消费计划触发点）；收集产物经 applyAddCollectedTasks 去重落 backlog
- *   （§14.3：只进 backlog，人工 promote 前不可执行/不可定时，守卫在状态机）；
- * - GitHub Webhook（§14.1）：`ingestGithubWebhook` 把 `issues` 事件按启用规则
- *   的标签过滤创建 backlog 任务（命令类字段递归拒绝，§14.3/§16.2）；HMAC
- *   校验在路由层（host-routes.ts）；
- * - 评论/产物/上下文快照（§9.5）：`add-comment`/`add-artifact`/`update-context`
- *   经状态机落账；每次执行结算后 Host 自动更新——成功时记录会话产物
- *   （type=session，transcript 即默认产物）并摘取最近 assistant 文本写入
- *   `contextSnapshot.lastAiSummary`（B5：Host 侧摘取 + token 预算），
- *   latestUserFeedback/relatedLinks 同步刷新；后续调用只注入摘要与必要片段
- *   （runner.launch 经 composePrompt，见 core/context.ts）。
- * T011 接入对话候选流转（§11.2/§14.4，P3.1）：`propose`（对话提取/手动转任务
- * → proposed 候选，source=conversation，输入清洗与命令字段拒绝在状态机/协议
- * 层）、`confirm`（确认候选 → 落 backlog/todo，确认是唯一 promote 路径——
- * 防注入闸门）、`dismiss`（拒绝/忽略删除）三个 action 经状态机落账。
- * T012 接入需求拆分（§11.2/§12.9/§14.5，P3.2，见 B8）：`start-split` 提交需求
- * （粘贴文本/工作区文件路径）→ 注册拆分作业 → 启动独立拆分会话（复用 T005
- * 执行通道，指令模板 = 粒度启发式 + 覆盖自检 + 输出 schema）→ 会话结束后读取
- * transcript、解析结构化标记 → 创建父需求任务「需求：<标题>」+ `propose-batch`
- * 原子落账（全部 proposed、source=requirement、children parentId 指向父任务、
- * 递归拆分挂到原任务下；人工确认闸门复用 T011）；`propose-batch` 亦可独立提交
- * （批量候选，parentId 引用校验与防环在状态机层，§16.8）。
- *
- * 分层：路由层（host-routes.ts）负责安全栅栏与载荷校验；本服务只认已解析的
- * 判别联合（protocol.ts 的输出），内部不含 HTTP 语义。调度（cron/one-shot/
- * 自动化规则，T006/T007/T010）、电源保护实现（后续任务）不在本基线内；
- * power 快照仅提供稳定的类型契约与基础值（sessionStateKnown 由轮询驱动）。
- */
 import type { SplitRequestInput, TaskRecord } from './core/model.ts';
 import { HostLedger } from './host-ledger.ts';
 import type { TaskBoardAutomationDeps } from './host-automation.ts';
 import type { ExecutionInspection, ExecutionSessionRow, ExecutionSessionState } from './host-runner.ts';
 import type { TaskBoardAction, TaskBoardEventPayload, TaskBoardPowerSnapshot, TaskBoardSnapshot } from './protocol.ts';
-/** 会话轮询间隔（§17 性能：5s，对齐参考实现）。 */
 export declare const SESSION_POLL_MS = 5000;
-/** 调度 tick 间隔（§13.1/§17 性能：30s，对齐参考实现）。 */
 export declare const SCHEDULE_TICK_MS = 30000;
-/** 超过该间隔视为 Host 停机/睡眠/长暂停（§13.1 错过不补跑；= tick + 15s 容差）。 */
 export declare const RESUME_GAP_MS: number;
-/** 本服务可注入的依赖面（§17 可测试性：Host 编排用结构面注入 fake）。 */
 export interface TaskBoardHostServiceOptions {
-    /** 账本（默认真实 HostLedger，测试注入临时目录账本）。 */
     ledger?: HostLedger;
-    /** 时钟（测试可注入）。 */
     now?: () => number;
-    /** 平台标识（测试可注入）。 */
     platform?: string;
-    /** 执行驱动（T005；缺省时 run/rerun 被拒绝，测试可注入 fake）。 */
     runner?: TaskBoardExecutionRunner;
-    /** 自动化收集依赖（T010；缺省 = 真实 fetch/文件读取，测试可注入 fake）。 */
     automation?: TaskBoardAutomationDeps;
 }
-/** 执行驱动面（§13）：launch 启动会话、listRunning 轮询、inspect 结算判定。 */
 export interface TaskBoardExecutionRunner {
-    /** 启动一次执行（fail-closed 钉住目标后创建会话并发送 Prompt），返回会话 id。 */
     launch(task: TaskRecord): Promise<string>;
-    /** 拉取会话列表（失败 known:false，服务层降级 sessionStateKnown）。 */
     listRunning(): Promise<ExecutionSessionState>;
-    /** 结算判定单条执行（pending/cancelled/failed/succeeded）。 */
     inspect(sessionId: string, startedAt: number, sessions?: readonly ExecutionSessionRow[]): Promise<ExecutionInspection>;
-    /**
-     * 读取会话 transcript 全文（T012/B8：需求拆分会话结果解析用）；会话不存在/
-     * 历史不可读 → undefined。拆分会话是独立专用会话，全文即拆分结果。
-     */
     readTranscriptText(sessionId: string): Promise<string | undefined>;
-    /**
-     * 停止底层会话（用户取消执行，§13.3）：尽力而为——缺省/失败不影响账本侧
-     * cancelled 结算（cancel-execution 的 ledger 落账不依赖它）。可缺省（测试
-     * fake 无需实现）。
-     */
     cancelSession?(sessionId: string): Promise<void>;
 }
-/**
- * 需求拆分作业（T012/B8，§12.9/§14.5）：一次 `start-split` 对应一个独立拆分
- * 会话（复用 T005 执行通道）。启动时注册（key = action.id，幂等重放不重复
- * 注册）；会话结束（不再 running）后读取 transcript → 解析结构化标记 → 创建
- * 父需求任务 + `propose-batch` 原子落账（全部 proposed，人工确认闸门复用
- * T011）。失败写 scheduler.error（UI 可见）并移除作业。
- */
 export interface SplitJob {
-    /** 拆分作业 id（= start-split action 的 id；幂等重放不重复注册）。 */
     id: string;
-    /** 拆分请求（标题/需求来源/归属/递归父任务）。 */
     input: SplitRequestInput;
-    /** 启动时刻（ms epoch）。 */
     startedAt: number;
-    /** 父需求任务 id（结算时创建；children 的 parentId 指向它）。 */
     parentId: string;
-    /** 拆分会话 id（launch 成功后回填）。 */
     sessionId?: string;
-    /** 是否已调度启动（幂等重放不重复启动）。 */
     launched?: boolean;
 }
-/** 任务看板协议服务：串行 apply + 幂等 + snapshot/event/power + 执行轮询。 */
 export declare class TaskBoardHostService {
-    /** 权威账本。 */
     readonly ledger: HostLedger;
     private readonly listeners;
     private readonly now;
@@ -140,164 +44,41 @@ export declare class TaskBoardHostService {
     private scheduleTimer;
     private tickInFlight;
     private lastScheduleTick;
-    /** 需求拆分作业（T012/B8：独立拆分会话驱动；key = action.id）。 */
     private readonly splitJobs;
     constructor(options?: TaskBoardHostServiceOptions);
-    /**
-     * 应用配置（插件 enabled / preventIdleSleep）。enabled=false 时 apply 抛错
-     * （路由层 400），SSE 订阅方通过事件帧感知 power 变化。从禁用恢复启用时
-     * 立即补一轮会话轮询与调度 tick（首 tick 跳过停机期错过的触发点）。
-     */
     setConfiguration(active: boolean, preventIdleSleep: boolean): void;
-    /** 全量状态快照（§11.1 `GET /state`）。 */
     snapshot(): TaskBoardSnapshot;
-    /** SSE 事件帧载荷（§11.1 `GET /events`）：只推 revision/scheduler/power。 */
     eventPayload(): TaskBoardEventPayload;
-    /** 订阅账本/配置变更（SSE 推送源；路由层在推送前先主动推一帧）。 */
     subscribe(listener: () => void): () => void;
-    /**
-     * 幂等应用一个已解析的 action（§11.3）：账本层判定 requestId + SHA-256 指纹，
-     * 命中缓存直接返回当前 state（不 bump）；首次请求经状态机守卫原子落账。
-     * 守卫/校验失败抛错（`TaskBoardTransitionError` 等），路由层转为 400。
-     *
-     * T005：`run/rerun` 在本次 apply 真实开启执行（revision +1）时，异步调度
-     * launch（创建会话 + 发送 Prompt）；幂等重放（revision 不变）不再重复启动。
-     */
     apply(requestId: string, action: TaskBoardAction): TaskBoardSnapshot;
-    /**
-     * 启动执行轮询（§13.3）：5s 间隔轮询会话列表结算 open 执行，启动时立即
-     * 轮询一次（覆盖 Host 重启后带 sessionId 的 running 执行）。幂等；无 runner
-     * 时 no-op（纯账本模式不轮询）。dispose 时停止。
-     *
-     * T006/T007 调度 tick（§13.1/§13.5）：30s 间隔扫描到期 cron 与 one-shot，
-     * 启动时立即 tick 一次——首个 tick 视为恢复（错过触发点跳过不补跑，见
-     * tickSchedule）。
-     */
     start(): void;
-    /** 释放：轮询/调度定时器、账本锁、订阅。 */
     dispose(): void;
-    /** 电源保护快照（§11.1 power 字段；保护实现随后续任务，本期为基础值 + 配置态）。 */
     powerSnapshot(): TaskBoardPowerSnapshot;
-    /** 状态机分发：协议 action → transitions 纯函数（就地修改账本文档并返回是否变更）。 */
     private applyAction;
-    /** 异步调度 launch（fire-and-forget；结算失败仅记录日志，不中断控制面）。 */
     private scheduleLaunch;
-    /**
-     * 异步停止底层会话（用户取消执行，§13.3）：尽力而为——runner 未接线/
-     * 不支持 cancelSession 时 no-op；RPC 失败仅记日志（账本侧 cancelled 结算
-     * 已权威，不因会话停止失败而回滚）。
-     */
     private scheduleSessionCancel;
-    /**
-     * launch 编排（§13.2 尾部）：runner 创建会话成功 → 回填 sessionId（之后由
-     * 轮询结算）；任何失败 → 结算 failed 并保留错误文本（会话创建后的失败携带
-     * sessionId，先回填再结算，详情页保留跳转线索）。
-     */
     private launchExecution;
-    /** 轮询调度（防重入）：单轮在途时跳过，dispose 后不再启动。 */
     private schedulePoll;
-    /**
-     * 单轮结算轮询（§13.3）：会话列表 → 逐条判定 open 执行；会话列表不可知时
-     * 仅降级 sessionStateKnown（不结算，避免误判）。重启恢复语义：
-     * - 有 sessionId 的 running 执行 → 继续观察结算（本方法覆盖）；
-     * - 无 sessionId 的启动中断 → HostLedger 加载时已标 cancelled（core/recovery.ts），
-     *   本方法跳过（禁止自动重发）。
-     * T012：同一轮次顺带结算需求拆分作业（复用会话列表，1 + E，B8）。
-     */
     private pollSessions;
-    /** 账本中全部未结算执行的最小投影（taskId/executionId/sessionId/startedAt）。 */
     private openExecutions;
     private setSessionStateKnown;
-    /** 调度 tick 调度（防重入）：单轮在途时跳过，dispose 后不再启动。 */
     private scheduleTick;
-    /**
-     * 单轮调度 tick（§13.1/§13.5）：
-     * - 记录 lastTickAt（setScheduler 不 bump revision，§17 性能）；
-     * - **恢复判定**：首个 tick（启动/从禁用恢复）或距上次 tick 超过
-     *   RESUME_GAP_MS（Host 停机/睡眠/长暂停）→ 跳过错过的触发点（skipMissed，
-     *   不补跑），并把全部到期规则滚动到 now 之后的下一个匹配点（cron）或写
-     *   firedAt 消费（one-shot）；
-     * - 正常 tick：扫描到期 cron（enabled 且 nextRunAt ≤ now 且非归档）与到期
-     *   one-shot（firedAt 缺省且 runAt ≤ now 且非归档），逐条开启执行（复用 T005
-     *   launch 入口）；同任务 running 中到期 → cron 只滚动不触发、one-shot 只写
-     *   firedAt 不触发（openScheduled/openScheduledOneShot 内部判定）。
-     */
     private tickSchedule;
-    /** 账本中当前到期（enabled 且 nextRunAt ≤ now）的自动化规则最小投影。 */
     private dueAutomationRules;
-    /** 账本中当前到期（enabled 且 nextRunAt ≤ now）的 cron 规则最小投影。 */
     private dueSchedules;
-    /**
-     * 开启一次到期的调度执行（§13.1/§13.2 尾部）：
-     * - 任务不存在/已归档 → no-op；
-     * - 任务 running 或带未结算执行 → **不并发、不排队**：本次只把 nextRunAt
-     *   滚动到下一匹配点（lastTriggeredAt 保留现值，本次不记触发），返回 undefined；
-     * - 否则开启执行（置 running + 追加 open 执行记录，startedAt=触发时刻）并把
-     *   规则滚动到下一匹配点（lastTriggeredAt=本次触发点），返回开启的执行供
-     *   scheduleLaunch 启动会话。
-     */
     private openScheduled;
-    /**
-     * 开启一次到期的 one-shot 执行（§13.5）：
-     * - 任务不存在/已归档 → no-op；
-     * - 任务 running 或带未结算执行 → **不并发、不排队**：本次仍标记消费
-     *   （写 firedAt），但不触发执行，返回 undefined；
-     * - 否则先标记消费（firedAt=now，触发即消费——防重启后重复触发），再开启
-     *   执行（置 running + 追加 open 执行记录，startedAt=触发时刻），返回开启的
-     *   执行供 scheduleLaunch 启动会话。
-     */
     private openScheduledOneShot;
-    /** 账本中当前到期（firedAt 缺省且 runAt ≤ now）的 one-shot 规则最小投影。 */
     private dueOneShots;
-    /** 异步调度一次收集（fire-and-forget；失败记日志，不中断控制面）。 */
     private scheduleAutomationRun;
-    /**
-     * 执行一次收集（§14.2）：按规则来源分发（书签收件箱文件 / GitHub API），产物
-     * 经 applyAddCollectedTasks 去重落 backlog（同 (source, url) 幂等）；收集失败
-     * 写入可见错误（scheduler.error，UI 可见），不抛给控制面。
-     */
     private runAutomationRule;
-    /**
-     * GitHub Webhook `issues` 事件摄入（§14.1）：命令类字段递归拒绝（§14.3/§16.2，
-     * 与 import 同一条红线）；只处理 opened/reopened；按启用 github_issue 规则的
-     * repo（配置了时须匹配）与标签过滤创建 backlog 任务（跨规则去重，同 url 只建
-     * 一条）。返回本次实际创建数（含账本去重）。
-     */
     ingestGithubWebhook(payload: unknown): {
         created: number;
     };
-    /**
-     * 注册拆分作业（start-split 的变更闭包）：校验递归父任务引用（存在性 + 防环，
-     * §16.8）后登记作业并返回 false（不产生账本变更、revision 不 bump——拆分
-     * 结果在拆分会话结算时落账）。幂等重放命中缓存不会调用本闭包 → 不重复注册。
-     */
     private registerSplitJob;
-    /** 异步调度拆分会话启动（fire-and-forget；失败记 scheduler.error，不中断控制面）。 */
     private scheduleSplitLaunch;
-    /**
-     * 启动拆分会话（B8）：合成拆分驱动任务（标题「需求拆分：<标题>」、Prompt =
-     * 拆分指令模板）复用 runner.launch（fail-closed 校验 + 创建会话 + 发送 Prompt）；
-     * 会话 id 回填作业（供轮询结算）。启动失败 → 记 scheduler.error 并移除作业。
-     */
     private launchSplit;
-    /** 拆分作业失败：移除作业 + scheduler.error（UI 可见）。 */
     private failSplit;
-    /**
-     * 单轮拆分作业结算（B8，复用 pollSessions 已取的会话列表，1 + E）：
-     * - sessionId 未回填（launch 进行中）→ 跳过；
-     * - 会话不在列表（被删/从未创建成功）→ 失败；
-     * - 会话仍在运行 → 跳过（等待 agent 完成拆分）；
-     * - 会话已结束 → 读取 transcript、解析标记、原子落账（settleSplit）。
-     */
     private pollSplitJobs;
-    /**
-     * 拆分结算（§12.9/§14.5）：解析 transcript 的结构化标记（`⟦task-board:split⟧`
-     * 逐条 + `⟦task-board:coverage⟧` 覆盖矩阵）→ 创建父需求任务 + `propose-batch`
-     * 原子落账（同一 mutate 闭包，任一失败整体回滚、revision 不变——§16.8）。
-     * 产物全部 proposed（source=requirement，人工确认闸门复用 T011）；children
-     * parentId 指向父需求任务；父任务递归拆分时挂到原任务下（§12.9）；候选
-     * metadata 携带拆分会话引用（可跳回追溯，§15）。解析不到任何条目 → 失败。
-     */
     private settleSplit;
     private emit;
 }