dsh-session-ops 0.1.4 → 0.2.1

package/lib/types/index.d.ts

@@ -0,0 +1,281 @@
+/**
+ * `dsh-session-ops` Host 半边（插件入口）。
+ *
+ * 这个包把原先两个独立插件合并成**一个** DSH 插件：
+ *   - `dsh-session-admin`（删除）→ {@link module:dsh-session-ops/admin}；
+ *   - `dsh-session-move`（搬迁）→ {@link module:dsh-session-ops/move}。
+ *
+ * 两个半边的代码是**逐字搬过来的**（见两个模块头部列出的差异清单），这里只做合并后的
+ * 那一层：一份配置 schema、一个活配置对象、一次 `loader/volatile-update` 订阅、
+ * 一个 `apply`，把两条路由与两个工具注册出去。
+ *
+ * ## 对外契约（合并后一条都不许变）
+ *
+ *   - HTTP：`/session-admin/api/<method>` 与 `/session-move/api/<method>` 的方法名、
+ *     入参、`{ok:true,value}` / `{ok:false,error:{code,message}}` 响应形状；
+ *   - 模型工具：`session_admin` 与 `session_move` 的名字、`parameters`、`output.schema`；
+ *   - 文档与排障产物：`$DSH_HOME/logs/dsh-session-admin.log`（`[时间] 级别 正文`）与
+ *     `$DSH_HOME/logs/dsh-session-move.log`（`时间 [级别] 正文`）两个文件与两种行格式；
+ *   - 安全默认：`allowWorkspaceSessions` / `allowLiveSessions` / `moveAllowHosts` /
+ *     `adminAllowHosts` / `memoryFollow` 一律落在安全的一侧（见 {@link Config}）。
+ *
+ * ## 配置键的合并方式
+ *
+ * 两半原先各有一个 `allowHosts`，但语义不同（删除半边按 `Host` 头解析 authority，
+ * 搬迁半边按 socket 的 `remoteAddress` 精确匹配），所以**拆成两个键**而不是合并：
+ *
+ * | 旧键（dsh-session-admin） | 旧键（dsh-session-move） | 新键 |
+ * | --- | --- | --- |
+ * | `enabled` | `enabled` | `enabled`（两半共用一个总开关） |
+ * | `allowHosts` | — | `adminAllowHosts` |
+ * | — | `allowHosts` | `moveAllowHosts` |
+ * | — | `root` | `root` |
+ * | `headerDeleteButton` | — | `headerDeleteButton` |
+ * | `allowWorkspaceSessions` | — | `allowWorkspaceSessions` |
+ * | `allowLiveSessions` | — | `allowLiveSessions` |
+ * | `maxBatch` | — | `maxBatch` |
+ * | — | `refuseRunning` | `refuseRunning` |
+ * | — | `maxSessions` | `maxSessions` |
+ * | — | `memoryFollow` | `memoryFollow` |
+ *
+ * 只有 `enabled` 是**语义合并**（两半原先各一个，现在一个）：任一旧值为 `false` 的
+ * 组合在新键下都会变成「全开或全关」，profile patch 要按新语义重写。
+ *
+ * @module dsh-session-ops
+ */
+import z from '@deepseek-ai/schemastery';
+import { ADMIN_API_PREFIX, createSessionAdmin, isInside, isTrustedRequest as isTrustedAdminRequest, mountAdmin } from './admin.js';
+import { MOVE_API_PREFIX, isTrustedRequest as isTrustedMoveRequest, mountForkMembershipRepair, mountMove, sweepForkChildrenOnBoot } from './move.js';
+import type { WorkspaceRegistryLike } from './store/registry.js';
+import type { SessionPersistenceLike } from './move.js';
+export { ADMIN_API_PREFIX, MOVE_API_PREFIX, createSessionAdmin, isInside, isTrustedAdminRequest, isTrustedMoveRequest, mountAdmin, mountForkMembershipRepair, mountMove, sweepForkChildrenOnBoot, };
+/**
+ * 搬迁半边原来的公开名（`dsh-session-move` 的 `API_PREFIX = '/session-move/api'`）。
+ *
+ * 合并后两半各有一个前缀，明确的名字是 {@link ADMIN_API_PREFIX} / {@link MOVE_API_PREFIX}；
+ * 这个别名留着，是为了让按 `dsh-session-move/lib/index.js` 写过 import 的脚本/测试不改也能跑。
+ */
+export declare const API_PREFIX = "/session-move/api";
+/** Cordis 插件名（profile 行 id 是 `session-toolbox`，两者刻意不同名）。 */
+export declare const name = "dsh-session-ops";
+/**
+ * 依赖的服务。**这不是可选的**：cordis 里没有声明 inject 就拿不到服务，
+ * `ctx.webServer` / `ctx.tools` / `ctx.sessions` / `ctx.sessionPersistence` 会静默是
+ * undefined——表现是日志照常打「mounted」但路由 404、工具根本没注册、守卫形同虚设。
+ *
+ * 两份清单的并集：删除半边要 `sessions`（Host 进程里挂着的会话），搬迁半边要
+ * `sessionPersistence`（会话根与写入句柄）。`workspaceRegistry` / `webServer` / `tools`
+ * 两边都要。
+ */
+export declare const inject: string[];
+/** 设置命名空间；与 client 半边 `settings.section` 的 id 必须一致。 */
+export declare const SETTINGS_NS = "session-toolbox";
+/**
+ * 插件配置（两份原配置的**并集**，键名与默认值见 {@link module:dsh-session-ops} 的表）。
+ *
+ * 键分两类，区别是**能不能在线改**：
+ *
+ *   - **旋钮**：标了 `.volatile()` 的字段由 Loader 以活引用（`{ get() }`）交给 `apply`，
+ *     写盘后原地更新引用、再补发一次 `loader/volatile-update`。插件页上本行的「配置」
+ *     卡片写的就是这 7 个字段，落盘在 profile 的 `cordis.patch.yml` 里，**不重启、不重挂**。
+ *   - **组合事实**：`enabled`（挂载期决定注册什么）、`root`（挂载期解析会话根）、
+ *     `adminAllowHosts` / `moveAllowHosts`（挂载期决定 HTTP 信任栅栏）。刻意不标 volatile：
+ *     不进表单，要改就改 profile 的 patch（改完本行会重挂一次）。
+ *
+ * `description` 会随 schema 进入表单描述，是界面文案的权威来源。
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    /** 总开关（两半共用）。关掉后两条路由与两个工具都不注册。改它需要重挂本行（非 volatile）。 */
+    enabled: z<boolean, boolean, "defined">;
+    /** 会话根目录；留空则从 `sessionPersistence.root` 推断（jsonl 后端会暴露它）。搬迁半边用。 */
+    root: z<string, string, "defined">;
+    /**
+     * 删除半边的额外信任 authority（`host` 或 `host:port`，按 `Host` 头解析）。
+     * 原 `dsh-session-admin` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    adminAllowHosts: z<string[], string[], "defined">;
+    /**
+     * 搬迁半边的额外信任 authority（`host` 或 `host:port`，按 socket 的 `remoteAddress`
+     * 精确匹配）。原 `dsh-session-move` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    moveAllowHosts: z<string[], string[], "defined">;
+    /** 是否允许删「属于某个工作区」的会话。默认否——工作区会话通常还想留。 */
+    allowWorkspaceSessions: z<boolean, boolean, "volatile-defined">;
+    /** 是否允许删仍然挂在 Host 进程里的会话（正在浏览/正在跑）。默认否。 */
+    allowLiveSessions: z<boolean, boolean, "volatile-defined">;
+    /** 一次调用最多删多少个，防手滑。 */
+    maxBatch: z<number, number, "volatile-defined">;
+    /**
+     * 是否在会话标题栏显示「删除当前会话」的垃圾桶图标。**默认开启。**
+     *
+     * 形态刻意是「图标 + 二次确认」而不是带字面标签的按钮：标签会招来点击，而这里
+     * 删的正是你正在用的会话。图标不占字面位置，误点最多弹出一个确认框，离真正删除
+     * 还隔着一步。清理由右侧「会话管理」面板或设置页承担，那是显式挑选动作。
+     *
+     * 这是个 volatile 旋钮：浏览器半边在挂载时问一次 Host（`config` 接口），所以
+     * 改完**刷新页面**就生效——不需要重启 dsh web，也不需要重挂本插件。
+     */
+    headerDeleteButton: z<boolean, boolean, "volatile-defined">;
+    /** 是否拒绝搬"正在跑一轮"的会话。默认拒绝——搬运期间它的写入句柄可能落盘。 */
+    refuseRunning: z<boolean, boolean, "volatile-defined">;
+    /** `list` 一次最多返回多少条会话（浏览器半边还要筛选）。 */
+    maxSessions: z<number, number, "volatile-defined">;
+    /**
+     * 项目作用域记忆的条目要不要跟着会话走。**默认 off**。
+     *
+     * 项目记忆是**工作区共享**的（一次写入、那个工作区里所有会话都读），所以把一条
+     * 会话的条目拖到另一个工作区会改变那边的记忆视图——只有"这条会话本来就该在目标
+     * 工作区"（纠正错放）时才该这么做：
+     *   - `off`  ：什么都不做。报告里仍给出**只读预览**（若开启会复制哪几条）。
+     *   - `copy` ：把该会话产出的条目（frontmatter `session:` 精确匹配）复制到目标
+     *              工作区，按文件名去重，源工作区不动。
+     *   - `move` ：同上，但复制后从源工作区移除（不可逆，谨慎）。
+     */
+    memoryFollow: z<string, string, "volatile-defined">;
+    /**
+     * 启动时是否做一轮「fork 子会话漏挂工作区」的定向扫描。
+     *
+     * 创建期的 `session/created` 补挂只挡住「Host fork 时就没挂」。记账写进去之后
+     * 又被抹掉的那一类（同机两个 Host 共用 `$DSH_HOME` 时，另一个进程用旧内存快照
+     * 重写 `storages/workspace.json`）只有启动期扫描能补回来，所以默认开启。
+     *
+     * 扫描范围收得很窄：只认带 `parentSession` 的普通 fork 子会话（排除 `origin:
+     * subagent` 与 `delegationDepth > 0`），且父会话已被某个工作区记账、子会话
+     * `cwd` 规范化后等于该工作区路径。刻意 ungrouped 的普通会话/迁移会话不碰。
+     */
+    repairForkChildrenOnBoot: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    /** 总开关（两半共用）。关掉后两条路由与两个工具都不注册。改它需要重挂本行（非 volatile）。 */
+    enabled: z<boolean, boolean, "defined">;
+    /** 会话根目录；留空则从 `sessionPersistence.root` 推断（jsonl 后端会暴露它）。搬迁半边用。 */
+    root: z<string, string, "defined">;
+    /**
+     * 删除半边的额外信任 authority（`host` 或 `host:port`，按 `Host` 头解析）。
+     * 原 `dsh-session-admin` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    adminAllowHosts: z<string[], string[], "defined">;
+    /**
+     * 搬迁半边的额外信任 authority（`host` 或 `host:port`，按 socket 的 `remoteAddress`
+     * 精确匹配）。原 `dsh-session-move` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    moveAllowHosts: z<string[], string[], "defined">;
+    /** 是否允许删「属于某个工作区」的会话。默认否——工作区会话通常还想留。 */
+    allowWorkspaceSessions: z<boolean, boolean, "volatile-defined">;
+    /** 是否允许删仍然挂在 Host 进程里的会话（正在浏览/正在跑）。默认否。 */
+    allowLiveSessions: z<boolean, boolean, "volatile-defined">;
+    /** 一次调用最多删多少个，防手滑。 */
+    maxBatch: z<number, number, "volatile-defined">;
+    /**
+     * 是否在会话标题栏显示「删除当前会话」的垃圾桶图标。**默认开启。**
+     *
+     * 形态刻意是「图标 + 二次确认」而不是带字面标签的按钮：标签会招来点击，而这里
+     * 删的正是你正在用的会话。图标不占字面位置，误点最多弹出一个确认框，离真正删除
+     * 还隔着一步。清理由右侧「会话管理」面板或设置页承担，那是显式挑选动作。
+     *
+     * 这是个 volatile 旋钮：浏览器半边在挂载时问一次 Host（`config` 接口），所以
+     * 改完**刷新页面**就生效——不需要重启 dsh web，也不需要重挂本插件。
+     */
+    headerDeleteButton: z<boolean, boolean, "volatile-defined">;
+    /** 是否拒绝搬"正在跑一轮"的会话。默认拒绝——搬运期间它的写入句柄可能落盘。 */
+    refuseRunning: z<boolean, boolean, "volatile-defined">;
+    /** `list` 一次最多返回多少条会话（浏览器半边还要筛选）。 */
+    maxSessions: z<number, number, "volatile-defined">;
+    /**
+     * 项目作用域记忆的条目要不要跟着会话走。**默认 off**。
+     *
+     * 项目记忆是**工作区共享**的（一次写入、那个工作区里所有会话都读），所以把一条
+     * 会话的条目拖到另一个工作区会改变那边的记忆视图——只有"这条会话本来就该在目标
+     * 工作区"（纠正错放）时才该这么做：
+     *   - `off`  ：什么都不做。报告里仍给出**只读预览**（若开启会复制哪几条）。
+     *   - `copy` ：把该会话产出的条目（frontmatter `session:` 精确匹配）复制到目标
+     *              工作区，按文件名去重，源工作区不动。
+     *   - `move` ：同上，但复制后从源工作区移除（不可逆，谨慎）。
+     */
+    memoryFollow: z<string, string, "volatile-defined">;
+    /**
+     * 启动时是否做一轮「fork 子会话漏挂工作区」的定向扫描。
+     *
+     * 创建期的 `session/created` 补挂只挡住「Host fork 时就没挂」。记账写进去之后
+     * 又被抹掉的那一类（同机两个 Host 共用 `$DSH_HOME` 时，另一个进程用旧内存快照
+     * 重写 `storages/workspace.json`）只有启动期扫描能补回来，所以默认开启。
+     *
+     * 扫描范围收得很窄：只认带 `parentSession` 的普通 fork 子会话（排除 `origin:
+     * subagent` 与 `delegationDepth > 0`），且父会话已被某个工作区记账、子会话
+     * `cwd` 规范化后等于该工作区路径。刻意 ungrouped 的普通会话/迁移会话不碰。
+     */
+    repairForkChildrenOnBoot: z<boolean, boolean, "defined">;
+}>>, "plain">;
+/**
+ * 解包后的插件配置（键名与 {@link Config} 一一对应，值都已收敛成普通值）。
+ *
+ * 手写而不是从 schemastery 推导：推到 `Config` 的完整类型会把 `.volatile()` 的
+ * `Volatile<T>` 包装也带出来，而 `apply` 里看到的永远是解包后的普通值。
+ */
+export interface SessionOpsConfig {
+    enabled: boolean;
+    root: string;
+    adminAllowHosts: string[];
+    moveAllowHosts: string[];
+    allowWorkspaceSessions: boolean;
+    allowLiveSessions: boolean;
+    maxBatch: number;
+    headerDeleteButton: boolean;
+    refuseRunning: boolean;
+    maxSessions: number;
+    memoryFollow: string;
+    repairForkChildrenOnBoot: boolean;
+}
+/**
+ * 解包 entry 配置里的 `.volatile()` 活引用，并交给 schema 校验补默认值。
+ *
+ * 实现在 `lib/store/host.js`：先解包输入、再校验、最后**再解包一次**——
+ * schemastery 对 `.volatile()` 字段输出的也是活引用，不收敛的话读到的就是 `{ get() }`
+ * 对象（HTTP 面上会变成一个空对象）。
+ * @param raw - entry 配置或普通配置对象。
+ * @returns 普通值配置。
+ */
+export declare function resolveConfig(raw?: Record<string, unknown>): SessionOpsConfig;
+/**
+ * Host cordis 上下文里本入口用到的那部分。
+ *
+ * DSH/Cordis 的 `Context` 在编译期拿不到（本包没有把 `@deepseek-ai/cordis` 列为依赖），
+ * 而这里只需要这几个成员：`inject` 声明过的服务、`ctx.get()`、`ctx.effect()`、`ctx.on()`。
+ */
+export interface SessionOpsContext {
+    logger?: Record<string, ((message: string) => unknown) | undefined> | undefined;
+    on: (event: string, handler: (...args: any[]) => unknown) => unknown;
+    effect: (fn: () => unknown, label?: string) => unknown;
+    get: (name: string) => any;
+    webServer: {
+        register(options: unknown): unknown;
+    };
+    tools: {
+        register(definition: unknown): unknown;
+    };
+    workspaceRegistry: WorkspaceRegistryLike;
+    sessionPersistence?: SessionPersistenceLike | undefined;
+}
+/**
+ * 挂载插件：两条路由 + 两个工具。
+ *
+ * 两个半边共用**同一个活配置对象**（见下），各自的信任栅栏读各自的那个键
+ * （`adminAllowHosts` / `moveAllowHosts`），所以 volatile 更新只需要在这里重读一次。
+ *
+ * 日志刻意保留两份、两种行格式：`$DSH_HOME/logs/dsh-session-admin.log`
+ * （`[时间] 级别 正文`）与 `$DSH_HOME/logs/dsh-session-move.log`（`时间 [级别] 正文`）
+ * 是合并前就存在的排障产物，合并后依然按各自的格式写各自那份。
+ *
+ * @param ctx - Host cordis 上下文（已 inject 五个服务）。
+ * @param rawConfig - 部署层配置。
+ * @returns 无。
+ */
+export declare function apply(ctx: SessionOpsContext, rawConfig?: Record<string, unknown>): void;
+/**
+ * 会话存储原语全量再导出（`lib/store/` 的五个模块）：
+ * `dshHome`、`encodeSegment`、`readSessionHeader`、`hasZstd`、`decodeProjectKey` 等。
+ *
+ * 原来的会话存储共享库根入口就是这个形状；合并成单包后保留同一份公开面，
+ * 外部按包名导入的脚本（如 dsh-open-in-dsh）只改包名即可，不必换符号名。
+ * 需要显式分层时也可以用子路径 `dsh-session-ops/store`（见 package.json exports）。
+ */
+export * from './store/index.js';

package/lib/types/memory.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 项目作用域记忆的「随会话走」支持（**可选，默认关**）。
+ *
+ * 背景：`dsh-cross-memory` 的项目作用域是**工作区级**的 —— 存到
+ * `$DSH_HOME/memories/projects/<slug>/entries/<id>.md`，slug 由工作区根目录派生
+ * （`slugify(basename)`，只取项目名、与机器路径无关，见其 storage.js）。
+ * 所以搬会话**不需要**搬记忆：会话换了 cwd，作用域自然跟到目标工作区。
+ * 但"这条会话在源工作区下写下的条目"留在源工作区，如果这次搬迁属于**纠正错放**
+ * （会话本来就该在目标工作区），那些条目也该一起过去。本模块只负责这一件事。
+ *
+ * 两条设计原则：
+ *   1. **默认不做**。项目记忆是工作区共享的，把单条会话的条目拖过去会改变另一个
+ *      工作区的记忆视图——这种事必须显式开启（`memoryFollow: 'copy' | 'move'`）。
+ *   2. **文件级、可逆、可预演**。`dsh-cross-memory` 的存储契约写明「条目文件才是真相源，
+ *      索引是可重建的缓存，手改/删除索引会在下次读取时自愈」，所以复制 `.md` 文件
+ *      就是受支持的写入方式，也不必依赖它的运行时。
+ *
+ * @module dsh-session-ops/memory
+ */
+/** 一个已存在的项目记忆目录。 */
+export interface ProjectMemoryDir {
+    slug: string;
+    root: string;
+    descriptorFile: string;
+    dir: string;
+}
+/** 一条被选中的记忆条目文件。 */
+export interface MemoryFollowEntry {
+    id: string;
+    title: string;
+    sourceFile: string;
+    targetFile: string;
+    existsInTarget: boolean;
+}
+/** {@link planMemoryFollow} 的计划（**只读**）。 */
+export interface MemoryFollowPlan {
+    projectsDir: string;
+    source: {
+        slug: string;
+        root: string;
+        dir: string;
+    } | null;
+    target: {
+        slug: string;
+        root: string;
+        dir: string;
+        descriptorFile: string;
+        existed: boolean;
+        planned?: boolean;
+    };
+    sessionId: string;
+    totalInSource: number;
+    matched: MemoryFollowEntry[];
+}
+/** {@link planMemoryFollow} 的选项。 */
+export interface MemoryFollowOptions {
+    dshHome: string;
+    sessionId: string;
+    fromCwd: string;
+    toCwd: string;
+}
+/** {@link applyMemoryFollow} 的结果。 */
+export interface MemoryFollowOutcome {
+    mode: string;
+    copied: number;
+    skipped: number;
+    removed: number;
+    files: string[];
+    removeError?: string;
+}
+/** 与 dsh-cross-memory/lib/storage.js 的 slugify 逐字一致。 */
+export declare function slugify(value: unknown): string;
+/**
+ * 与 dsh-cross-memory/lib/storage.js 的 projectSlug 逐字一致：**只取项目名**，
+ * 不再拼 `sha1(resolve(root))` 后缀。dsh-cross-memory 已把项目 slug 改成
+ * 「一台机器上算出来、另一台也对得上」的名字派生（旧的后缀方案会把同一个
+ * 项目按机器拆成多个目录，迁移逻辑见其 storage.ts 的 LEGACY_PROJECT_SLUG）。
+ */
+export declare function projectSlug(root: string): string;
+/** `$DSH_HOME/memories/projects`。 */
+export declare function projectsDirOf(dshHome: string): string;
+/**
+ * 在 projects 目录里按 root 找已存在的项目（优先命中已有 slug，避免算出第二个目录）。
+ * @param projectsDir - `…/memories/projects`。
+ * @param root - 工作区根目录。
+ * @returns `{slug, root, descriptorFile, dir}`，没有时 `undefined`。
+ */
+export declare function findProjectByRoot(projectsDir: string, root: string): ProjectMemoryDir | undefined;
+/** 极简 frontmatter 解析：只认 `key: value` 单行（dsh-cross-memory 的条目就是这种形状）。 */
+export declare function parseFrontmatter(text: string): Record<string, string>;
+/**
+ * 计算一次「记忆随会话走」的计划。**只读**。
+ *
+ * @param options - `{dshHome, sessionId, fromCwd, toCwd}`。
+ * @returns 计划：源/目标项目、匹配到的条目（按 frontmatter 的 `session:` 归属过滤）。
+ */
+export declare function planMemoryFollow(options: MemoryFollowOptions): MemoryFollowPlan;
+/**
+ * 执行计划。`copy` 只加不删；`move` 复制后从源项目移除（= 纠正错放）。
+ * 目标已有同名条目时跳过（不覆盖、按名去重）。
+ *
+ * @param plan - {@link planMemoryFollow} 的返回值。
+ * @param mode - `'copy'` 或 `'move'`。
+ * @returns `{mode, copied, skipped, removed, files}`。
+ */
+export declare function applyMemoryFollow(plan: MemoryFollowPlan, mode: string): MemoryFollowOutcome;

package/lib/types/move.d.ts

@@ -0,0 +1,272 @@
+/**
+ * `dsh-session-ops` 的**搬迁半边**（原 `dsh-session-move` 插件的 Host 半边）。
+ *
+ * 这一半的代码搬自原 `dsh-session-move` 的 `lib/index.js`，差异只有四处：
+ *   - 插件 entry 的 `name` / `inject` / `Config` / `resolveConfig` / `apply` 上移到
+ *     `lib/index.js`（合并后只有一个 entry、一份配置 schema、一个 `apply`）；
+ *   - `API_PREFIX` 改名 `MOVE_API_PREFIX`（删除半边占着 `ADMIN_API_PREFIX`）；
+ *   - 配置键 `allowHosts` 改名 `moveAllowHosts`（与 `adminAllowHosts` 语义不同）；
+ *   - 原 `apply` 里"建配置/建日志/订阅 volatile/看 enabled"那段上移到入口，剩下的接线
+ *     成为 `mountMove(ctx, config, log)`。
+ * 其余一字未动（`createMover`、`/session-move/api` 的方法表、`session_move` 工具定义、
+ * socket 版信任栅栏、注释）。`./engine.js` / `./memory.js` / `./sessionlog.js` 也原样搬来。
+ *
+ * 能力：把一条已持久化的会话搬到另一个工作区——**真搬迁**：
+ *   1. 会话日志搬到目标工作区的 project 目录，header 的 `cwd` 改写成目标路径；
+ *   2. 目标工作区 `attachSession`、原工作区 `detachSession`（工作区注册表成员随动）；
+ *   3. 若该会话此刻正被 Host 持有（`ctx.sessions` 里挂着），同时改写内存里的
+ *      `session.header.cwd` 与持久化写入句柄的 header，让它之后继续往新位置写。
+ *
+ * 一处硬边界：**正在跑一轮的会话一律拒绝**（`refuseRunning` 默认 true）。它的写入句柄
+ * 随时可能落盘，搬家窗口里挪目录会让这一轮的事件写到一个不存在的位置（ENOENT）。
+ *
+ * 会话存储的公共知识（路径命名、帧读写、注册表成员/归档集合、「正在跑」判定、
+ * 宿主与 HTTP 面的底座）在 `lib/store/` 里；本文件只保留搬迁策略本身。
+ *
+ * @module dsh-session-ops/move
+ */
+import type { HttpRequest } from './store/http.js';
+import { dshHome } from './store/host.js';
+import type { LogFn } from './store/host.js';
+import type { PersistenceLike, WorkspaceEntity, WorkspaceRegistryLike } from './store/registry.js';
+import type { MoveReport } from './engine.js';
+import type { MemoryFollowOutcome } from './memory.js';
+import type { SessionOpsConfig } from './index.js';
+/** HTTP 路由前缀（两半各一条，合并后仍然分开）。 */
+export declare const MOVE_API_PREFIX = "/session-move/api";
+/**
+ * `$DSH_HOME`（环境变量优先，默认 `~/.dsh`）。
+ *
+ * 实现在 `lib/store/host.js`——它与删除半边用的是同一份；
+ * 这里再导出，保持本仓库的公开面不变。
+ */
+export { dshHome };
+/**
+ * loopback 或显式白名单 authority 才放行，并额外拒绝浏览器侧的跨站 / 跨源请求。
+ *
+ * 原先这份栅栏只按 socket 的 `remoteAddress` 判断回环、`allowHosts` 只做精确字符串
+ * 匹配，**不看 `sec-fetch-site` / `Origin`**——恶意页面从任意站点 POST 到本机
+ * `127.0.0.1:3080` 时，socket 地址同样是回环，只看 `remoteAddress` 拦不住。
+ * 2026-09-25 与 `dsh-session-admin` 那份栅栏对齐（那条缺口已补），差异只剩
+ * 「本份以 `remoteAddress` 为回环判据、admin 以 `Host` 头为判据」。
+ * 共享包只提供路由骨架（`createApiHandler`），栅栏以回调形式传进去。
+ */
+export declare function isTrustedRequest(req: HttpRequest, allowHosts: string[]): boolean;
+/** 持久化后端 `list()` 返回的一条会话快照。 */
+export interface SessionSnapshotLike {
+    id?: unknown;
+    header: Record<string, unknown>;
+}
+/** 持久化后端 `open()` 返回的读句柄。 */
+export interface PersistenceHandleLike {
+    header: Record<string, unknown>;
+    inheritedEventCount?: unknown;
+    read(): Promise<{
+        events?: unknown[];
+    } | undefined>;
+    close(): Promise<unknown>;
+}
+/** 搬迁半边用到的持久化后端能力（`ctx.sessionPersistence` 的子集）。 */
+export interface SessionPersistenceLike extends PersistenceLike {
+    list: () => Promise<SessionSnapshotLike[]>;
+    open: (sessionId: string, mode: string) => Promise<PersistenceHandleLike>;
+}
+/** `list` 快照里的一行工作区。 */
+export interface WorkspaceSummary {
+    id: string;
+    title: string;
+    path: string;
+    visible: number;
+    accounted: number;
+}
+/** `list` 快照里的一条会话。 */
+export interface SessionRow {
+    id: string;
+    cwd: string | null;
+    createdAt: number | null;
+    resident: boolean;
+    running: string | null;
+    hasWriteHandle: boolean;
+    archived: boolean;
+    workspaceId: string | null;
+    workspaceTitle: string | null;
+    movable: boolean;
+}
+/** {@link Mover.list} 的返回。 */
+export interface ListSnapshot {
+    root: string;
+    compression: string;
+    zstd: boolean;
+    workspaces: WorkspaceSummary[];
+    sessions: SessionRow[];
+    counts: {
+        stored: number;
+        resident: number;
+        workspaces: number;
+    };
+}
+/** `mover.move` 的入参（HTTP / 工具都把浏览器或模型给的对象原样递进来）。 */
+export interface MoveRequest {
+    sessionId?: unknown;
+    targetWorkspace?: unknown;
+    dryRun?: unknown;
+}
+/** 计划摘要在报告里的形状。 */
+export interface MovePlanSummary {
+    generation: string;
+    version: number;
+    compressed: boolean;
+    bytesBefore: number;
+    bytesAfter: number;
+    frames: number | null;
+    sourcePath: string;
+    targetPath: string;
+    leaseFile: string | null;
+    leftInSourceDir: string[];
+    otherGenerations: string[];
+}
+/** 记忆跟随预览/结果摘要在报告里的形状。 */
+export interface MemoryFollowSummary {
+    mode: string;
+    sourceSlug?: string | null;
+    targetSlug?: string;
+    targetHadProject?: boolean;
+    sourceEntries?: number;
+    matched?: number;
+    titles?: string[];
+    alreadyInTarget?: number;
+    note?: string;
+    error?: string;
+    applied?: MemoryFollowOutcome;
+    applyError?: string;
+}
+/** `mover.verify` 的读回结果。 */
+export interface VerifyReadback {
+    headerCwd: string | null;
+    inheritedEventCount: number;
+    events: number | null;
+}
+/** {@link Mover.move} 的完整报告。字段按路径可选（noop / attach-only / dry-run）。 */
+export interface MoveActionReport {
+    sessionId: string;
+    from: string;
+    to: string;
+    workspace: {
+        id: string;
+        title: string;
+    };
+    dryRun: boolean;
+    running: string | null;
+    noop?: boolean;
+    note?: string;
+    attachOnly?: boolean;
+    dryRunOnly?: boolean;
+    plan?: MovePlanSummary;
+    memoryFollow?: MemoryFollowSummary;
+    storage?: MoveReport;
+    handleFlushError?: string;
+    writeHandleRedirected?: boolean;
+    liveHeaderUpdated?: boolean;
+    registryHeaderCacheUpdated?: boolean;
+    attachedTo?: string;
+    detachedFrom?: string;
+    detachError?: string;
+    dshReadback?: VerifyReadback;
+    dshReadbackError?: string;
+    memoryScope?: string;
+    ok?: boolean;
+}
+/** `list` / `move` / `verify` 三个入口（`createMover` 的返回）。 */
+export interface Mover {
+    list: () => Promise<ListSnapshot>;
+    move: (request: MoveRequest) => Promise<MoveActionReport>;
+    verify: (sessionId: string) => Promise<VerifyReadback>;
+    rootOf: () => string;
+    compressionOf: () => string;
+    resolveWorkspace: (key: unknown) => WorkspaceEntity | undefined;
+}
+/** {@link createMover} 用到的 Host 上下文（最小本地接口，见 `src/index.ts` 的说明）。 */
+export interface MoveContext {
+    sessionPersistence?: SessionPersistenceLike | undefined;
+    workspaceRegistry: WorkspaceRegistryLike;
+    get: (name: string) => any;
+    webServer: {
+        register(options: unknown): unknown;
+    };
+    tools: {
+        register(definition: unknown): unknown;
+    };
+    effect: (fn: () => unknown, label?: string) => unknown;
+}
+/**
+ * 挂载搬迁半边：路由 + 工具。
+ *
+ * 与删除半边刻意不同的两点（原样保留的理由）：
+ *   - 信任栅栏看 socket 的 `remoteAddress`（`isTrustedRequest`），`allowHosts` 只做精确
+ *     字符串匹配；删除半边看 `Host` 头；
+ *   - 请求体按**严格模式**读（`requireObject: true`，非普通对象一律 400）。
+ *
+ * @param ctx - Host cordis 上下文（`webServer` / `tools` / `sessionPersistence` /
+ *   `workspaceRegistry`；`sessions` / `agents` 是可选事实源，用 `ctx.get` 取）。
+ * @param config - 已解包的**活配置对象**（身份由入口保持，volatile 更新时原地覆盖）。
+ * @param log - `(level, message) => void`（入口传的是 move 那套行格式的文件日志）。
+ * @returns 无。
+ */
+export declare function mountMove(ctx: MoveContext, config: SessionOpsConfig, log: LogFn): void;
+/** 成员自愈扫描的汇总。 */
+export interface ForkSweepReport {
+    checked: number;
+    attached: number;
+    skipped?: string;
+}
+/** 成员自愈器（创建期监听与启动期扫描共用）。 */
+export interface ForkMembershipRepairer {
+    repair: (sessionId: string, header: Record<string, unknown> | undefined, reason: string) => Promise<void>;
+    ownerOf: (sessionId: string) => WorkspaceEntity | undefined;
+}
+/**
+ * 成员自愈用到的 Host 上下文（`workspaceRegistry` 可缺：缺了就跳过自愈）。
+ */
+export interface RepairContext {
+    workspaceRegistry?: WorkspaceRegistryLike | undefined;
+    sessionPersistence?: SessionPersistenceLike | undefined;
+    on: (event: string, handler: (...args: any[]) => unknown) => unknown;
+}
+/**
+ * 启动期的成员自愈扫描：把**已经丢掉记账**的 fork 子会话补回去。
+ *
+ * ## 为什么创建期补挂不够（实测的第二条证据链）
+ *
+ * `session/created` 那一刻补挂只挡住「Host fork 时就没挂」这一种。实测中有些 fork
+ * 在 Host 侧确实走了 `workspace.attachSession(childId)`（RPC 返回成功、插件侧没有
+ * `fork 失败` 日志），但子会话最终仍不在任何工作区的 `sessionIds` 里——也就是说
+ * 记账**写进去之后又没了**。同一个时间窗里，父会话的归档也没落住。
+ *
+ * 能同时抹掉「新 attach」与「归档集合」的只有一件事：**另一个 Host 进程用自己内存里
+ * 的旧快照重写了 `$DSH_HOME/storages/workspace.json`**。存储层是整文件原子替换、
+ * 无跨进程锁（`dsh-storage-json` 的注释写的就是「一个 unit 文件只有一个写者，后写
+ * 覆盖先写是对的」），而同一台机器上同时跑两个 Host、共用同一个 `~/.dsh` 就会出现
+ * 这类丢失。这类丢失发生在 attach 之后，创建期的补挂拦不住。
+ *
+ * 所以这里补一道**启动期**的定向扫描：只处理 fork 子会话（`isForkChild`），且仍然
+ * 要求「父会话已被工作区记账 + 子会话 cwd 规范化后等于该工作区路径」；不碰子代理、
+ * 不碰没有父会话的普通会话，也不做全量 attach，避免改写用户刻意留着的 ungrouped。
+ *
+ * 幂等：已记账直接跳过；失败只记日志，绝不让插件挂载失败。
+ *
+ * @param ctx - Host cordis 上下文（需要 `workspaceRegistry` 与 `sessionPersistence`）。
+ * @param config - 活配置对象；`repairForkChildrenOnBoot === false` 时跳过整轮扫描。
+ * @param log - `(level, message) => void`。
+ * @param shared - 与创建期监听器共享的 repairer（`mountForkMembershipRepair` 内部用）。
+ * @returns 扫描结束（含跳过）后 resolve 的报告；永不 reject。
+ */
+export declare function sweepForkChildrenOnBoot(ctx: RepairContext, config?: Partial<SessionOpsConfig>, log?: LogFn, shared?: ForkMembershipRepairer): Promise<ForkSweepReport>;
+/**
+ * 挂载 fork 子会话的成员自愈：创建期监听 + 启动期定向扫描。
+ *
+ * @param ctx - Host cordis 上下文。
+ * @param config - 活配置对象。
+ * @param log - `(level, message) => void`。
+ * @returns 启动期扫描的 Promise（Host/cordis 忽略；测试可 await 以确定性观察结果）。
+ */
+export declare function mountForkMembershipRepair(ctx: RepairContext, config: Partial<SessionOpsConfig>, log: LogFn): Promise<ForkSweepReport> | undefined;

package/lib/types/sessionlog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 会话日志的帧级读写原语 —— **实现在本包的 `lib/store/` 里**（`dsh-session-ops`）。
+ *
+ * 这个文件现在只是一层**历史路径的门面**：`./sessionlog.js` 曾经是本插件私有的
+ * 实现（从 dsh-sync 移植），而删除半边那边重复着同一套知识的另一半
+ * （`decodeProjectKey`）。两个插件合并成 `dsh-session-ops` 之后：
+ *   - 实现只有一份，规则与边界都写在 `lib/store/paths.js` / `lib/store/frames.js`
+ *     的模块注释里；
+ *   - 这里的模块路径保留下来，是为了让本包原有的 `test/*.mjs` 不必改 import 就继续可用。
+ *
+ * @module dsh-session-ops/sessionlog
+ */
+export { CHECKSUM_OPTIONS, ZSTD_MAGIC, hasZstd, readHeaderFromBuffer, rewriteHeaderCwd, scanZstdFrames, } from './store/frames.js';
+export { compressionSuffix, encodeSegment, generationLogFilename, logPath, projectKey, sessionDir, } from './store/paths.js';