dsh-task-ledger 0.0.46 → 0.0.48

package/dist/host/repositories/cache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 读缓存（方案 B 的落地件，2026-10-18 拍板的三条口径，无黑魔法）：
+ *
+ * ① 进程内 `Map`，key = `op:workspace:filter`（filter 已序列化），值 = 结果 + 时间戳；
+ * ② 命中且 1.5s 内直接返回、**不起进程**；同 key 并发**单飞**（只跑一次脚本，其余等同一个 Promise）；
+ * ③ `fresh=1` 绕过（路由层先 `invalidate()` 再算）；写路径成功后 `invalidate(workspaceId)` 钩子。
+ *
+ * 边界：只缓存 skill 脚本的两读（在办 list / 历史 history）。worklog 正文不缓存——它会被
+ * 会话里的 Agent 实时改写，缓存 1.5s 也会让用户看到上一版。**失败不入缓存**（错就是错，重试要能重新跑）。
+ * 命中返回的是**同一个引用**：调用方只许读（上层 service 全是纯计算，不原地改数组）。
+ */
+/** 缓存有效期（2026-10-18 拍板 1.5s：够挡同一屏的重复读，短到不会让人看到旧数据）。 */
+export declare const CACHE_TTL_MS = 1500;
+/** 缓存的操作种类（= skill 脚本子命令；worklog 不进缓存故不在此列）。 */
+export type CacheOp = 'list' | 'history';
+/** 缓存键：`op:workspace:filter` 三条信息都要，否则不同筛选 / 不同工作区会串味。 */
+export declare function cacheKey(workspaceId: string, op: CacheOp, detail: string): string;
+/**
+ * 取数（命中即返回，未命中跑 `load` 并落缓存）。
+ * `now` 仅供冒烟注入；业务代码不传，默认取当前时刻。
+ */
+export declare function cached<T>(key: string, load: () => Promise<T>, now?: number): Promise<T>;
+/**
+ * 让缓存失效：不传 = 全清（`fresh=1` 手动刷新用）；传工作区 id = 只清该工作区。
+ * 写路径（任务 4，未拍板）落地后在其成功后调本函数；现在只有手动刷新这一处用。
+ */
+export declare function invalidate(workspaceId?: string): void;

package/dist/host/repositories/cache.js

@@ -0,0 +1,57 @@
+/**
+ * 读缓存（方案 B 的落地件，2026-10-18 拍板的三条口径，无黑魔法）：
+ *
+ * ① 进程内 `Map`，key = `op:workspace:filter`（filter 已序列化），值 = 结果 + 时间戳；
+ * ② 命中且 1.5s 内直接返回、**不起进程**；同 key 并发**单飞**（只跑一次脚本，其余等同一个 Promise）；
+ * ③ `fresh=1` 绕过（路由层先 `invalidate()` 再算）；写路径成功后 `invalidate(workspaceId)` 钩子。
+ *
+ * 边界：只缓存 skill 脚本的两读（在办 list / 历史 history）。worklog 正文不缓存——它会被
+ * 会话里的 Agent 实时改写，缓存 1.5s 也会让用户看到上一版。**失败不入缓存**（错就是错，重试要能重新跑）。
+ * 命中返回的是**同一个引用**：调用方只许读（上层 service 全是纯计算，不原地改数组）。
+ */
+/** 缓存有效期（2026-10-18 拍板 1.5s：够挡同一屏的重复读，短到不会让人看到旧数据）。 */
+export const CACHE_TTL_MS = 1_500;
+const SEP = '\u0000';
+/** 已完成的缓存：key → 值与时间戳。 */
+const settled = new Map();
+/** 在途单飞：key → 正在跑的 Promise（同 key 并发只跑一次）。 */
+const inflight = new Map();
+/** 缓存键：`op:workspace:filter` 三条信息都要，否则不同筛选 / 不同工作区会串味。 */
+export function cacheKey(workspaceId, op, detail) {
+    return `${op}${SEP}${workspaceId}${SEP}${detail}`;
+}
+/**
+ * 取数（命中即返回，未命中跑 `load` 并落缓存）。
+ * `now` 仅供冒烟注入；业务代码不传，默认取当前时刻。
+ */
+export function cached(key, load, now = Date.now()) {
+    const hit = settled.get(key);
+    if (hit !== undefined && now - hit.at < CACHE_TTL_MS)
+        return Promise.resolve(hit.value);
+    const pending = inflight.get(key);
+    if (pending !== undefined)
+        return pending;
+    const task = Promise.resolve()
+        .then(load)
+        .then((value) => {
+        settled.set(key, { at: Date.now(), value });
+        return value;
+    })
+        .finally(() => { inflight.delete(key); });
+    inflight.set(key, task);
+    return task;
+}
+/**
+ * 让缓存失效：不传 = 全清（`fresh=1` 手动刷新用）；传工作区 id = 只清该工作区。
+ * 写路径（任务 4，未拍板）落地后在其成功后调本函数；现在只有手动刷新这一处用。
+ */
+export function invalidate(workspaceId) {
+    if (workspaceId === undefined) {
+        settled.clear();
+        return;
+    }
+    for (const key of settled.keys()) {
+        if (key.split(SEP)[1] === workspaceId)
+            settled.delete(key);
+    }
+}

package/dist/host/repositories/ledger.repository.d.ts

@@ -12,10 +12,10 @@ export declare function hasLedger(workspacePath: string): boolean;
 /**
  * 在办任务（包 `list --json`；结果过 records 入口校验后打上 workspace）。
  * 脚本失败 / 形状不符抛错——由 service 层捕获进 degraded，路由层转 500 + 人话，
- * 不静默返空（空 = 撒谎）。
+ * 不静默返空（空 = 撒谎）。**过 1.5s 读缓存**（同屏多端点会反复读同一份在办）。
  */
 export declare function readTasks(workspace: LedgerWorkspace, filter?: LedgerFilter): Promise<TaskRow[]>;
-/** 已结案记录（包 `history --json`；`records` 必须存在且为数组，缺了即坏数据）。 */
+/** 已结案记录（包 `history --json`；`records` 必须存在且为数组，缺了即坏数据）。同样过读缓存。 */
 export declare function readHistory(workspace: LedgerWorkspace, filter?: LedgerFilter): Promise<HistoryRecord[]>;
 /** 单条在办（展开行 / 详情用）。取不到回 null，不抛。 */
 export declare function getTask(workspace: LedgerWorkspace, taskId: string): Promise<TaskRow | null>;

package/dist/host/repositories/ledger.repository.js

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { runLedgerScript } from './runner.js';
 import { parseHistoryRecords, parseTaskList } from './records.js';
+import { cacheKey, cached } from './cache.js';
 /** 台账目录名（各工作区根下的这一个目录；布局知识只在本文件出现一次）。 */
 const LEDGER_DIR = 'ledger';
 /**
@@ -39,20 +40,28 @@ export function hasLedger(workspacePath) {
 /**
  * 在办任务（包 `list --json`；结果过 records 入口校验后打上 workspace）。
  * 脚本失败 / 形状不符抛错——由 service 层捕获进 degraded，路由层转 500 + 人话，
- * 不静默返空（空 = 撒谎）。
+ * 不静默返空（空 = 撒谎）。**过 1.5s 读缓存**（同屏多端点会反复读同一份在办）。
  */
 export async function readTasks(workspace, filter = {}) {
-    const result = await runLedgerScript('list', ['--repo', workspace.path, '--json', ...filterArgs(filter)]);
-    if (!result.ok)
-        throw new Error(`${workspace.title}: ${result.error}`);
-    return parseTaskList(result.data, workspace);
+    return await cached(cacheKey(workspace.id, 'list', argsKey(filter)), async () => {
+        const result = await runLedgerScript('list', ['--repo', workspace.path, '--json', ...filterArgs(filter)]);
+        if (!result.ok)
+            throw new Error(`${workspace.title}: ${result.error}`);
+        return parseTaskList(result.data, workspace);
+    });
 }
-/** 已结案记录（包 `history --json`；`records` 必须存在且为数组，缺了即坏数据）。 */
+/** 已结案记录（包 `history --json`；`records` 必须存在且为数组，缺了即坏数据）。同样过读缓存。 */
 export async function readHistory(workspace, filter = {}) {
-    const result = await runLedgerScript('history', ['--repo', workspace.path, '--json', ...filterArgs(filter)]);
-    if (!result.ok)
-        throw new Error(`${workspace.title}: ${result.error}`);
-    return parseHistoryRecords(result.data, workspace);
+    return await cached(cacheKey(workspace.id, 'history', argsKey(filter)), async () => {
+        const result = await runLedgerScript('history', ['--repo', workspace.path, '--json', ...filterArgs(filter)]);
+        if (!result.ok)
+            throw new Error(`${workspace.title}: ${result.error}`);
+        return parseHistoryRecords(result.data, workspace);
+    });
+}
+/** 缓存键的 filter 段：脚本参数原样序列化（分隔符取不可见字符，值里带空格也不会串）。 */
+function argsKey(filter) {
+    return filterArgs(filter).join('\u0001');
 }
 /** 单条在办（展开行 / 详情用）。取不到回 null，不抛。 */
 export async function getTask(workspace, taskId) {

package/dist/host/routes.d.ts

@@ -5,6 +5,7 @@
  * 见 external/host-webserver.md。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type AgentsLike } from './services/session.service.js';
 import { type RegistryWorkspace } from './workspace.js';
 /** 宿主 webServer.register 的最小面（WebRoute 形状见 external/host-webserver.md）。 */
 export interface WebServerLike {
@@ -22,3 +23,19 @@ export interface RouteDeps {
     readonly registry: WorkspaceRegistryLike;
 }
 export declare function registerRoutes(webServer: WebServerLike, deps: RouteDeps): void;
+export interface SessionRouteDeps {
+    readonly registry: WorkspaceRegistryLike;
+    /** 起会话的服务面；宿主缺就回 503 人话（端点照常注册，前端不用按版本分支）。 */
+    readonly agents: AgentsLike | undefined;
+    /** 惰性服务读取：`agentPresets` / `agentDefaultModel` 可能整条不存在，或被 ctx 的 inject 门挡住。 */
+    readonly getService: (name: string) => unknown;
+}
+/**
+ * 注册「结束任务」端点：`POST /close`。
+ *
+ * 为什么只有这一条走会话（2026-10-18 用户拍板）：认领 / 释放没有判断量，host 直写即可；
+ * **结束**要带用户留言、要模型读过程文档后写真摘要 —— 只能交给会话里的 Agent 做。
+ *
+ * 请求体：`{ ws, id, message?, provider?, model? }`；响应：`{ sessionId, warning? }`。
+ */
+export declare function registerSessionRoutes(webServer: WebServerLike, deps: SessionRouteDeps): void;

package/dist/host/routes.js

@@ -1,5 +1,9 @@
 import { getHomeAggregate, getFilterOptions, queryClosed } from './board.js';
+import { getSnapshot } from './services/home.service.js';
+import { getTrend } from './services/trend.service.js';
 import { getTask, readTasks, readWorklog } from './repositories/ledger.repository.js';
+import { invalidate } from './repositories/cache.js';
+import { HandoffError, startCloseSession, } from './services/session.service.js';
 import { resolveWorkspaces } from './workspace.js';
 /** API 前缀（唯一真源就在这一处）。 */
 const API_PREFIX = '/api/task-ledger';
@@ -52,90 +56,235 @@ function workspacesOf(deps) {
     return resolveWorkspaces(deps.registry.list());
 }
 export function registerRoutes(webServer, deps) {
-    webServer.register({
-        kind: 'exact',
-        path: `${API_PREFIX}/workspaces`,
-        handler: (_req, res) => { sendJson(res, 200, { workspaces: workspacesOf(deps) }); },
-    });
+    /**
+     * 注册一个**读**端点：统一先看 `?fresh=1`（手动刷新 = 清缓存再算，别让用户按了刷新还看旧数）。
+     * 缓存 TTL 只有 1.5s，正常浏览照样吃缓存；写端点将来自己走写路径 + `invalidate()`，不走这里。
+     */
+    const registerRead = (path, handler) => {
+        webServer.register({
+            kind: 'exact',
+            path: `${API_PREFIX}${path}`,
+            handler: async (req, res) => {
+                if (new URL(req.url ?? '/', 'http://localhost').searchParams.get('fresh') === '1')
+                    invalidate();
+                await handler(req, res);
+            },
+        });
+    };
+    registerRead('/workspaces', (_req, res) => { sendJson(res, 200, { workspaces: workspacesOf(deps) }); });
     // 首页一次拿全：在办快照 + 近 8 周趋势 + 四个自然周期计数（host 每个工作区只读一次）。
-    webServer.register({
-        kind: 'exact',
-        path: `${API_PREFIX}/board`,
-        handler: async (_req, res) => {
-            try {
-                const home = await getHomeAggregate(workspacesOf(deps));
-                sendJson(res, 200, { ...home.snapshot, closed: home.closed, trend: home.trend, degraded: home.degraded });
+    registerRead('/board', async (_req, res) => {
+        try {
+            const home = await getHomeAggregate(workspacesOf(deps));
+            sendJson(res, 200, { ...home.snapshot, closed: home.closed, trend: home.trend, degraded: home.degraded });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    // ── 拆端点（2026-10-18 步骤 4a：纯加法，旧 /board 全量原样保留）──
+    // 快路径：首屏。只读 progress.json + git 身份，**不碰 history** ⇒ 耗时与历史总量解耦
+    // （20 万条量级实测 527ms vs 合并端点 4.4s）。
+    registerRead('/board/snapshot', async (_req, res) => {
+        try {
+            const result = await getSnapshot(workspacesOf(deps));
+            sendJson(res, 200, { ...result.snapshot, degraded: result.degraded });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    // 慢路径：趋势（近 8 周 + 四个自然周期）。读 history ⇒ 异步/按需拉，首屏不等它。
+    registerRead('/board/trend', async (_req, res) => {
+        try {
+            const result = await getTrend(workspacesOf(deps));
+            sendJson(res, 200, { closed: result.closed, trend: result.trend, degraded: result.degraded });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    registerRead('/tasks', async (req, res) => {
+        try {
+            const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
+            const perWorkspace = await Promise.all(workspacesOf(deps).map((workspace) => readTasks(workspace, filter)));
+            sendJson(res, 200, { tasks: perWorkspace.flat() });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    // 任务详情 + 过程文档正文（query 传 ws/id，不做路径段解析——任务号含中文和连字符）。
+    registerRead('/task', async (req, res) => {
+        try {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            const workspace = workspacesOf(deps).find((item) => item.id === url.searchParams.get('ws'));
+            const taskId = url.searchParams.get('id');
+            if (workspace === undefined || taskId === null) {
+                sendJson(res, 400, { error: '缺少 ws / id 参数' });
+                return;
             }
-            catch (error) {
-                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            const task = await getTask(workspace, taskId);
+            if (task === null) {
+                sendJson(res, 404, { error: '任务不存在' });
+                return;
             }
-        },
+            sendJson(res, 200, { task, worklog: await readWorklog(workspace, task) });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    registerRead('/history', async (req, res) => {
+        try {
+            const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
+            const result = await queryClosed(workspacesOf(deps), filter);
+            sendJson(res, 200, { records: result.records, degraded: result.degraded });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
     });
+    registerRead('/filters', async (_req, res) => {
+        try {
+            const result = await getFilterOptions(workspacesOf(deps));
+            sendJson(res, 200, { ...result.options, degraded: result.degraded });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+}
+// ───────────────────────── 会话交接（按钮侧 · 写类端点） ─────────────────────────
+/** 写端点请求体上限：只收一小段用户留言，别让人往这塞文件。 */
+const BODY_LIMIT = 64 * 1024;
+/** 读请求体（宿主 handler 收原始 req，没有 body parser；超上限直接拒，不缓冲垃圾）。 */
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > BODY_LIMIT)
+            throw new Error('body-too-large');
+        chunks.push(buffer);
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (text.trim() === '')
+        return {};
+    return JSON.parse(text);
+}
+/**
+ * 同源守卫（architecture 不变量 6 的落地）：浏览器 fetch 必带与 Host 同源的 `Origin`；
+ * 没有 `Origin` 的（本机脚本 / Desktop IPC）只放行回环地址。
+ * 读端点保持现状（只读无副作用）；**会起会话的写端点必须过这道**。
+ */
+function isTrustedRequest(req) {
+    const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
+    const host = typeof req.headers.host === 'string' ? req.headers.host : undefined;
+    if (origin === undefined) {
+        const address = req.socket.remoteAddress;
+        return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+    }
+    if (host === undefined)
+        return false;
+    try {
+        return new URL(origin).host === host;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 注册「结束任务」端点：`POST /close`。
+ *
+ * 为什么只有这一条走会话（2026-10-18 用户拍板）：认领 / 释放没有判断量，host 直写即可；
+ * **结束**要带用户留言、要模型读过程文档后写真摘要 —— 只能交给会话里的 Agent 做。
+ *
+ * 请求体：`{ ws, id, message?, provider?, model? }`；响应：`{ sessionId, warning? }`。
+ */
+export function registerSessionRoutes(webServer, deps) {
     webServer.register({
         kind: 'exact',
-        path: `${API_PREFIX}/tasks`,
+        path: `${API_PREFIX}/close`,
         handler: async (req, res) => {
-            try {
-                const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
-                const perWorkspace = await Promise.all(workspacesOf(deps).map((workspace) => readTasks(workspace, filter)));
-                sendJson(res, 200, { tasks: perWorkspace.flat() });
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { error: '「结束任务」只支持 POST' });
+                return;
             }
-            catch (error) {
-                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            if (!isTrustedRequest(req)) {
+                sendJson(res, 403, { error: '只接受同源请求' });
+                return;
             }
-        },
-    });
-    // 任务详情 + 过程文档正文（query 传 ws/id，不做路径段解析——任务号含中文和连字符）。
-    webServer.register({
-        kind: 'exact',
-        path: `${API_PREFIX}/task`,
-        handler: async (req, res) => {
+            let body;
             try {
-                const url = new URL(req.url ?? '/', 'http://localhost');
-                const workspace = workspacesOf(deps).find((item) => item.id === url.searchParams.get('ws'));
-                const taskId = url.searchParams.get('id');
-                if (workspace === undefined || taskId === null) {
-                    sendJson(res, 400, { error: '缺少 ws / id 参数' });
-                    return;
-                }
-                const task = await getTask(workspace, taskId);
-                if (task === null) {
-                    sendJson(res, 404, { error: '任务不存在' });
-                    return;
-                }
-                sendJson(res, 200, { task, worklog: await readWorklog(workspace, task) });
+                body = await readJsonBody(req);
             }
             catch (error) {
-                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                const tooLarge = error instanceof Error && error.message === 'body-too-large';
+                sendJson(res, tooLarge ? 413 : 400, { error: tooLarge ? '请求体过大' : '请求体不是合法 JSON' });
+                return;
             }
-        },
-    });
-    webServer.register({
-        kind: 'exact',
-        path: `${API_PREFIX}/history`,
-        handler: async (req, res) => {
-            try {
-                const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
-                const result = await queryClosed(workspacesOf(deps), filter);
-                sendJson(res, 200, { records: result.records, degraded: result.degraded });
+            const fields = typeof body === 'object' && body !== null ? body : {};
+            const str = (key) => (typeof fields[key] === 'string' ? fields[key] : '');
+            const workspaceId = str('ws');
+            const taskId = str('id');
+            if (workspaceId === '' || taskId === '') {
+                sendJson(res, 400, { error: '缺少 ws / id 参数' });
+                return;
             }
-            catch (error) {
-                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            const provider = str('provider');
+            const model = str('model');
+            if ((provider === '') !== (model === '')) {
+                sendJson(res, 400, { error: 'provider 与 model 必须成对给出' });
+                return;
+            }
+            const workspace = workspacesOf(deps).find((item) => item.id === workspaceId);
+            if (workspace === undefined) {
+                sendJson(res, 404, { error: '工作区不存在或不含台账' });
+                return;
             }
-        },
-    });
-    webServer.register({
-        kind: 'exact',
-        path: `${API_PREFIX}/filters`,
-        handler: async (_req, res) => {
             try {
-                const result = await getFilterOptions(workspacesOf(deps));
-                sendJson(res, 200, { ...result.options, degraded: result.degraded });
+                const result = await startCloseSession({
+                    agents: deps.agents,
+                    presets: deps.getService('agentPresets'),
+                    defaultModel: deps.getService('agentDefaultModel'),
+                }, {
+                    workspace,
+                    taskId,
+                    message: str('message'),
+                    model: provider === '' ? undefined : { provider, model },
+                });
+                const warning = await attachSession(deps, workspaceId, result.sessionId) ?? result.warning;
+                sendJson(res, 200, warning === undefined ? { sessionId: result.sessionId } : { sessionId: result.sessionId, warning });
             }
             catch (error) {
+                if (error instanceof HandoffError) {
+                    const status = error.code === 'task-missing'
+                        ? 404
+                        : error.code === 'no-agents' || error.code === 'no-preset' || error.code === 'no-model' ? 503 : 500;
+                    sendJson(res, status, { error: error.message, code: error.code });
+                    return;
+                }
                 sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
             }
         },
     });
-    // POST /sessions（按钮会话交接）归「任务按钮与会话交接」任务——写入路径 A/B 拍板后再接。
+}
+/**
+ * 会话归组（best effort）：登记进工作区 `sessionIds`，否则侧栏里找不到这个会话。
+ * 缺失 / 失败都不算致命——会话本身已经建好、跳转可用，只如实回一条 warning。
+ */
+async function attachSession(deps, workspaceId, sessionId) {
+    const entity = deps.registry.list().find((item) => item.id === workspaceId);
+    if (entity === undefined || typeof entity.attachSession !== 'function') {
+        return '会话已建，但宿主该工作区没有 attachSession 面：会话不会出现在工作区列表里';
+    }
+    try {
+        await entity.attachSession(sessionId);
+        return undefined;
+    }
+    catch (error) {
+        return `会话已建，但没能挂进工作区列表：${error instanceof Error ? error.message : String(error)}`;
+    }
 }

package/dist/host/services/session.service.d.ts

@@ -0,0 +1,110 @@
+import type { LedgerWorkspace } from '../types.js';
+/** 模型路由：provider 与 model 必须成对。 */
+export interface ModelRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** 会话首条 user 消息（`@deepseek-ai/dsh-llm` UserMessage 的最小同形面）。 */
+export interface UserMessageLike {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+    /**
+     * 生产者自有 kind（宿主 v4 格式要求；`kind: 'plugin'` 已废弃会被拒）。
+     * form/summary 给官方界面渲染成通知卡用。
+     */
+    readonly source: {
+        readonly kind: string;
+        readonly form: 'notice';
+        readonly summary: string;
+    };
+}
+/** `ctx.agents` 最小面（`CreateAgentOptions` 见 session-handoff 文档 §二）。 */
+export interface AgentsLike {
+    create(options: {
+        readonly sessionId: string;
+        readonly meta?: {
+            readonly cwd?: string;
+            readonly agentPreset?: string;
+        };
+        readonly agentOptions?: {
+            readonly provider?: string;
+            readonly model?: string;
+        };
+        readonly setup?: (agentCtx: unknown) => void | Promise<void>;
+    }): Promise<{
+        readonly agent: {
+            send(message: UserMessageLike, target: 'next-turn' | 'next-step', wakeup: boolean): void;
+        };
+    }>;
+}
+/** `ctx.agentPresets` 最小面：resolve 省略 id = 部署默认；mount 只在 setup 里调得到。 */
+export interface AgentPresetsLike {
+    resolve(id?: string): Promise<{
+        readonly id: string;
+    }>;
+    mount(agentCtx: unknown, id?: string): Promise<unknown>;
+}
+/** `ctx.agentDefaultModel` 最小面（部署默认模型）。 */
+export interface DefaultModelLike {
+    currentSelection(): ModelRoute;
+}
+/** 交接失败的原因码（路由层据此给状态码，文案在这里写成能直接上界面的）。 */
+export type HandoffErrorCode = 'no-agents' | 'no-preset' | 'no-model' | 'task-missing' | 'create-failed' | 'send-failed';
+export declare class HandoffError extends Error {
+    readonly code: HandoffErrorCode;
+    constructor(code: HandoffErrorCode, message: string);
+}
+/** 结束任务的预置提示词入参（纯数据，便于冒烟直接断言文案）。 */
+export interface ClosePromptInput {
+    readonly title: string;
+    readonly taskId: string;
+    /** 任务所在工作区绝对路径（`--repo` 就是它）。 */
+    readonly workspacePath: string;
+    /** 过程文档相对 `ledger/` 的路径；缺失传 null，提示词如实说「没有」。 */
+    readonly worklogPath: string | null;
+    /** 用户在弹框里留的话（可为空）。 */
+    readonly message: string;
+}
+/**
+ * 「结束任务」提示词（2026-10-18 用户口述定稿）。
+ *
+ * 结构照用户原话：**预置说明在前，用户留言放最末**（越靠后、越只讲一件事的段落遵守率越高 ——
+ * 参考插件真机结论）。三道硬约束缺一不可：
+ * ① 不要开新会话（用户：我要结束这个流程了，不能让模型再开一堆框）；
+ * ② 读过程文档后直接收尾（别再回头问，用户已经留言了）；
+ * ③ 写台账只经 skill 脚本（插件不手改文件，close 由模型执行）。
+ */
+export declare function buildClosePrompt(input: ClosePromptInput): string;
+/** 交接入参（路由层校验完协议字段后给）。 */
+export interface CloseHandoffRequest {
+    readonly workspace: LedgerWorkspace;
+    readonly taskId: string;
+    readonly message: string;
+    /** 用户选的模型；不给 = 用宿主默认。 */
+    readonly model?: ModelRoute;
+}
+export interface CloseHandoffResult {
+    readonly sessionId: string;
+    /** 非致命问题（如会话没能挂进工作区列表），如实回给调用方显示，不吞。 */
+    readonly warning?: string;
+}
+/** 依赖面（都是惰性服务，缺了给 503 人话，不硬崩）。 */
+export interface CloseHandoffDeps {
+    readonly agents: AgentsLike | undefined;
+    readonly presets: AgentPresetsLike | undefined;
+    readonly defaultModel: DefaultModelLike | undefined;
+}
+/**
+ * 起一个「结束任务」会话并发出首条提示词。
+ * 失败抛 {@link HandoffError}（带原因码）；成功返回 sessionId 供客户端 `openSession` 跳转。
+ */
+export declare function startCloseSession(deps: CloseHandoffDeps, request: CloseHandoffRequest): Promise<CloseHandoffResult>;
+/**
+ * 模型路由：用户选了就必须给全一对（只有一半 = 配错，直接人话拒绝）；
+ * 没选就走宿主部署默认。**没有兜底猜测**——猜一个模型去结案比报错更糟。
+ */
+export declare function resolveModelRoute(defaultModel: DefaultModelLike | undefined, explicit?: ModelRoute): ModelRoute;