dsh-task-ledger 0.0.45 → 0.0.47

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

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+/**
+ * 当前 git 身份（cwd = 该工作区）——「我的待办」判定源。
+ * 与 agent 在会话里跑 skill 时的取值环境一致；取不到回 null（非 git 目录 / 没配身份），
+ * 该工作区的「我的」统计按 0 计（不谎报）。
+ *
+ * 全 host 唯一 spawn git 的地方（python3 的唯一出口在 ./runner.ts）。
+ */
+export function getCurrentIdentity(workspace) {
+    return new Promise((resolve) => {
+        const child = spawn('git', ['config', 'user.name'], { cwd: workspace.path, stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.on('error', () => { resolve(null); });
+        child.on('close', (code) => {
+            const name = stdout.trim();
+            resolve(code === 0 && name !== '' ? name : null);
+        });
+    });
+}

package/dist/host/{ledger-read.d.ts → repositories/ledger.repository.d.ts}

@@ -1,15 +1,21 @@
-import type { HistoryRecord, LedgerFilter, LedgerWorkspace, TaskRow } from './types.js';
+import type { HistoryRecord, LedgerFilter, LedgerWorkspace, TaskRow } from '../types.js';
 /**
  * LedgerFilter → skill 脚本参数（只拼调用方给了的；undefined 一律不拼，
  * 让脚本走自己的默认——插件不替脚本决定默认值）。
  */
 export declare function filterArgs(filter: LedgerFilter): string[];
 /**
- * 在办任务（包 `list --json`；结果打上 workspace）。
- * 脚本失败抛错——路由层转 500 + 人话，不静默返空（空 = 撒谎）。
+ * 台账工作区探测：`<path>/ledger/progress.json` 在才算（未初始化 = 后端不可见，
+ * 2026-10-17 拍板）。全 host 对台账目录的 IO 只在本文件——别处再写 existsSync 即为分层倒退。
+ */
+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`；结果打上 workspace）。 */
+/** 已结案记录（包 `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

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+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';
+/**
+ * LedgerFilter → skill 脚本参数（只拼调用方给了的；undefined 一律不拼，
+ * 让脚本走自己的默认——插件不替脚本决定默认值）。
+ */
+export function filterArgs(filter) {
+    const args = [];
+    if (filter.status !== undefined)
+        args.push('--status', filter.status);
+    if (filter.owner !== undefined)
+        args.push('--owner', filter.owner);
+    if (filter.category !== undefined)
+        args.push('--category', filter.category);
+    if (filter.tag !== undefined)
+        args.push('--tag', filter.tag);
+    if (filter.since !== undefined)
+        args.push('--since', filter.since);
+    if (filter.until !== undefined)
+        args.push('--until', filter.until);
+    if (filter.limit !== undefined)
+        args.push('--limit', String(filter.limit));
+    if (filter.months !== undefined)
+        args.push('--months', String(filter.months));
+    return args;
+}
+/**
+ * 台账工作区探测：`<path>/ledger/progress.json` 在才算（未初始化 = 后端不可见，
+ * 2026-10-17 拍板）。全 host 对台账目录的 IO 只在本文件——别处再写 existsSync 即为分层倒退。
+ */
+export function hasLedger(workspacePath) {
+    return existsSync(path.join(workspacePath, LEDGER_DIR, 'progress.json'));
+}
+/**
+ * 在办任务（包 `list --json`；结果过 records 入口校验后打上 workspace）。
+ * 脚本失败 / 形状不符抛错——由 service 层捕获进 degraded，路由层转 500 + 人话，
+ * 不静默返空（空 = 撒谎）。**过 1.5s 读缓存**（同屏多端点会反复读同一份在办）。
+ */
+export async function readTasks(workspace, filter = {}) {
+    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` 必须存在且为数组，缺了即坏数据）。同样过读缓存。 */
+export async function readHistory(workspace, filter = {}) {
+    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) {
+    const rows = await readTasks(workspace);
+    return rows.find((row) => row.id === taskId) ?? null;
+}
+/**
+ * 过程文档正文（`task.worklog` 相对 `ledger/` 的路径）。
+ * 读不到回 null（文件被清 / 路径坏都不炸——由调用方展示「过程文档缺失」）。
+ */
+export async function readWorklog(workspace, task) {
+    const relative = task.worklog;
+    if (relative === undefined || relative === null || relative === '')
+        return null;
+    try {
+        return await readFile(path.join(workspace.path, LEDGER_DIR, relative), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,5 @@
+import type { HistoryRecord, LedgerWorkspace, TaskRow } from '../types.js';
+/** `list --json`（任务号为键的对象）→ TaskRow[]（打上 id 与 workspace）。 */
+export declare function parseTaskList(raw: unknown, workspace: LedgerWorkspace): TaskRow[];
+/** `history --json`（`{count, filters, records}`）→ HistoryRecord[]（打上 workspace）。 */
+export declare function parseHistoryRecords(raw: unknown, workspace: LedgerWorkspace): HistoryRecord[];

package/dist/host/repositories/records.js

@@ -0,0 +1,48 @@
+/**
+ * 入口校验（纯函数）：skill 脚本 JSON → 领域对象。
+ *
+ * 口径：**容器级严格、元素级宽松**。
+ * - 容器：`list --json` 顶层必须是 plain object（任务号为键）；`history --json` 的 `records`
+ *   必须存在且为数组（现状 `records ?? []` 的容忍在脚本回归时会静默产出空历史 = 撒谎）；
+ * - 元素：是 object 就收，字段缺失一律放行（TaskRecord 全字段可选是脚本既有契约，
+ *   旧 8 列 history 不因此被误杀）。
+ * 失败抛 {@link LedgerDataError}——由 service 层捕获进 degraded，不静默。
+ */
+import { LedgerDataError } from '../errors.js';
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** `list --json`（任务号为键的对象）→ TaskRow[]（打上 id 与 workspace）。 */
+export function parseTaskList(raw, workspace) {
+    if (!isPlainObject(raw)) {
+        throw new LedgerDataError(workspace.id, `${workspace.title}: 台账 list 输出不是「任务号为键的对象」，拒绝当成空列表`);
+    }
+    const rows = [];
+    for (const [id, value] of Object.entries(raw)) {
+        if (!isPlainObject(value)) {
+            throw new LedgerDataError(workspace.id, `${workspace.title}: 任务 ${id} 不是对象，台账格式可能已变`);
+        }
+        if (id === '') {
+            throw new LedgerDataError(workspace.id, `${workspace.title}: 台账存在空任务号，格式可能已变`);
+        }
+        rows.push({ ...value, id, workspace });
+    }
+    return rows;
+}
+/** `history --json`（`{count, filters, records}`）→ HistoryRecord[]（打上 workspace）。 */
+export function parseHistoryRecords(raw, workspace) {
+    if (!isPlainObject(raw)) {
+        throw new LedgerDataError(workspace.id, `${workspace.title}: 台账 history 输出不是对象，拒绝当成空历史`);
+    }
+    const records = raw.records;
+    if (!Array.isArray(records)) {
+        throw new LedgerDataError(workspace.id, `${workspace.title}: 台账 history 输出缺 records 数组，格式可能已变`);
+    }
+    const rows = [];
+    for (const record of records) {
+        if (!isPlainObject(record))
+            continue; // 元素级宽松：坏行跳过，不整板炸
+        rows.push({ ...record, workspace });
+    }
+    return rows;
+}

package/dist/host/{script.js → repositories/runner.js}

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 /**
- * 内嵌 skill 脚本的默认路径：dist/host/script.js → 包根 skill/scripts/progress.py。
+ * 内嵌 skill 脚本的默认路径：dist/host/repositories/runner.js → 包根 skill/scripts/progress.py
+ * （比原 host/script.js 深一层 ⇒ 相对路径多一级 `../`）。
  * 构建时 scripts/copy-skill.mjs 把 packages/skill 拷到 packages/plugin/skill/。
  */
-const DEFAULT_SCRIPT_PATH = fileURLToPath(new URL('../../skill/scripts/progress.py', import.meta.url));
+const DEFAULT_SCRIPT_PATH = fileURLToPath(new URL('../../../skill/scripts/progress.py', import.meta.url));
 /** 单次脚本调用超时上限（ms）。实测单仓 5 万行全量 1.2s，10s 是宽松上限。 */
 const DEFAULT_TIMEOUT_MS = 10_000;
 /**

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 { getTask, readTasks, readWorklog } from './ledger-read.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';
@@ -47,93 +51,240 @@ function filterFromQuery(url) {
         filter.months = months;
     return filter;
 }
-/** 每请求重新解析工作区（registry 可能刚变；existsSync × N 是微秒级，不缓存）。 */
+/** 每请求重新解析工作区（registry 可能刚变；探测走 hasLedger()，微秒级，不缓存）。 */
 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 });
+    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'));
-                sendJson(res, 200, { records: await queryClosed(workspacesOf(deps), filter) });
+            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 {
-                sendJson(res, 200, await getFilterOptions(workspacesOf(deps)));
+                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/dates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 日期口径（纯函数层，零 IO）：本机时区、周一为一周之始（与 skill 脚本同口径）。
+ * 所有函数显式收 `now`——不自己读时钟，便于单测与跨时区复现。
+ */
+/** Date → `YYYY-MM-DD`。 */
+export declare function ymd(date: Date): string;
+/** 时刻串（`YYYY-MM-DD HH:mm:ss` / `YYYY-MM-DD`）→ 日期部分；解析不了回 null。 */
+export declare function dayOf(stamp: string | null | undefined): string | null;
+/** 某日期所在周的周一（00:00）。 */
+export declare function mondayOf(day: string): Date;
+/**
+ * 第 offset 周的起止（offset 0 = 本周，-1 = 上周；返回日期串，含边界）。
+ * ⚠️ 本周只到今天（周还没结束），上周才是完整周一~周日——否则「本周」会把明天之后的
+ * 日子也画进区间，tooltip 里的截止日撒谎。
+ */
+export declare function weekWindow(offset: number, now: Date): {
+    from: string;
+    to: string;
+};
+/** 第 offset 月的起止（offset 0 = 本月，-1 = 上月；含边界）。
+ *  同 {@link weekWindow}：本月只到今天，上月才是完整自然月。 */
+export declare function monthWindow(offset: number, now: Date): {
+    from: string;
+    to: string;
+};
+/** 日期是否落在 [from, to]（含边界，字符串比较即可——ISO 字典序即时间序）。 */
+export declare function inWindow(day: string | null, window: {
+    from: string;
+    to: string;
+}): boolean;
+/** 「YYYY-MM-DD HH:mm:ss」→ 距今天数（解析不了 / 未来都按 0；不编造）。 */
+export declare function daysSince(stamp: string | null | undefined, now: Date): number | null;
+/** 近 N 周的桶骨架（`{week, end}`，历史周 end=周日、当前周 end=今天）。 */
+export declare function buildWeeks(count: number, now: Date): readonly {
+    week: string;
+    end: string;
+}[];

package/dist/host/services/dates.js

@@ -0,0 +1,71 @@
+/**
+ * 日期口径（纯函数层，零 IO）：本机时区、周一为一周之始（与 skill 脚本同口径）。
+ * 所有函数显式收 `now`——不自己读时钟，便于单测与跨时区复现。
+ */
+function pad(value) {
+    return String(value).padStart(2, '0');
+}
+/** Date → `YYYY-MM-DD`。 */
+export function ymd(date) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** 时刻串（`YYYY-MM-DD HH:mm:ss` / `YYYY-MM-DD`）→ 日期部分；解析不了回 null。 */
+export function dayOf(stamp) {
+    if (stamp === null || stamp === undefined || stamp === '')
+        return null;
+    const day = String(stamp).slice(0, 10);
+    return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : null;
+}
+/** 某日期所在周的周一（00:00）。 */
+export function mondayOf(day) {
+    const date = new Date(`${day}T00:00:00`);
+    date.setDate(date.getDate() - ((date.getDay() + 6) % 7));
+    return date;
+}
+/**
+ * 第 offset 周的起止（offset 0 = 本周，-1 = 上周；返回日期串，含边界）。
+ * ⚠️ 本周只到今天（周还没结束），上周才是完整周一~周日——否则「本周」会把明天之后的
+ * 日子也画进区间，tooltip 里的截止日撒谎。
+ */
+export function weekWindow(offset, now) {
+    const monday = mondayOf(ymd(now));
+    monday.setDate(monday.getDate() + offset * 7);
+    const sunday = new Date(monday);
+    sunday.setDate(sunday.getDate() + 6);
+    const last = offset === 0 ? now : sunday;
+    return { from: ymd(monday), to: ymd(last < sunday ? last : sunday) };
+}
+/** 第 offset 月的起止（offset 0 = 本月，-1 = 上月；含边界）。
+ *  同 {@link weekWindow}：本月只到今天，上月才是完整自然月。 */
+export function monthWindow(offset, now) {
+    const first = new Date(now.getFullYear(), now.getMonth() + offset, 1);
+    const last = new Date(now.getFullYear(), now.getMonth() + offset + 1, 0);
+    const end = offset === 0 ? now : last;
+    return { from: ymd(first), to: ymd(end < last ? end : last) };
+}
+/** 日期是否落在 [from, to]（含边界，字符串比较即可——ISO 字典序即时间序）。 */
+export function inWindow(day, window) {
+    return day !== null && day >= window.from && day <= window.to;
+}
+/** 「YYYY-MM-DD HH:mm:ss」→ 距今天数（解析不了 / 未来都按 0；不编造）。 */
+export function daysSince(stamp, now) {
+    if (stamp === null || stamp === undefined || stamp === '')
+        return null;
+    const parsed = new Date(String(stamp).replace(' ', 'T'));
+    if (Number.isNaN(parsed.getTime()))
+        return null;
+    const days = Math.floor((now.getTime() - parsed.getTime()) / 86_400_000);
+    return days > 0 ? days : 0;
+}
+/** 近 N 周的桶骨架（`{week, end}`，历史周 end=周日、当前周 end=今天）。 */
+export function buildWeeks(count, now) {
+    const weeks = [];
+    for (let offset = count - 1; offset >= 0; offset -= 1)
+        weeks.push(weekWindow(-offset, now).from);
+    return weeks.map((week, i) => {
+        const monday = new Date(`${week}T00:00:00`);
+        const sunday = new Date(monday);
+        sunday.setDate(sunday.getDate() + 6);
+        return { week, end: i === weeks.length - 1 ? ymd(now) : ymd(sunday) };
+    });
+}