dsh-session-ops 0.0.0-stage → 0.2.0

package/lib/engine.js

@@ -0,0 +1,236 @@
+/**
+ * 搬迁引擎：把一条会话日志从「旧 cwd 的 project 目录」搬到「新 cwd 的 project 目录」，
+ * 并改写 header 里的 cwd。不依赖 cordis，便于单测（见 test/core.test.mjs）。
+ *
+ * 命名与格式事实（都来自 dsh-session-persistence-jsonl 的实测与源码）：
+ *   - 日志路径 `<root>/<projectKey(cwd)>/<encodeSegment(id)>/session[.vN].jsonl[.zstd]`；
+ *   - `findLog` 会扫**所有** project 目录找同一个 id，多于一处就抛
+ *     `duplicate JSONL session id ... appears in multiple project directories`；
+ *   - generation 文件名必须规范（v0 不带 `vN`），临时名/带后缀的备份名不会被当成 generation。
+ * 因此搬迁必须做到「任何时刻都不存在两份规范名的日志」，见 {@link applyPlan} 的三步改名。
+ *
+ * @module dsh-session-ops/engine
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, openSync, writeSync, fsyncSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { ZSTD_MAGIC, readHeaderFromBuffer, rewriteHeaderCwd, scanZstdFrames, } from './store/frames.js';
+import { findGeneration, parseGenerationName, projectKey, sessionDir, } from './store/paths.js';
+import { messageOf } from './store/util.js';
+/** 迁移中使用的临时文件名后缀（都**不**匹配 generation 规范名）。 */
+export const TMP_SUFFIX = '.session-move-tmp';
+export const PARKED_SUFFIX = '.session-move-old';
+/**
+ * `findGeneration` / `parseGenerationName`（「目录里哪份才算规范 generation」）已经搬到
+ * `lib/store/paths.js`——删除路径也要认得同一套命名，规则只该有一份。
+ * 这里保留再导出，是为了不打断本仓库既有的导入者（`test/core.test.mjs` 就按
+ * `../lib/engine.js` 导入它们）。
+ */
+export { findGeneration, parseGenerationName };
+/**
+ * 计算一次搬迁的计划：读源日志、改写 cwd、给出目标路径。**只读**，不写任何东西。
+ *
+ * @param options - `{root, sessionId, fromCwd, toCwd, compression}`。
+ * @returns 计划对象（含 `buffer`，供 {@link applyPlan} 直接落盘）。
+ * @throws 源日志缺失、header 与请求不符、目标已存在、源与目标同目录时。
+ */
+export function planMove(options) {
+    const { root, sessionId, fromCwd, toCwd } = options;
+    const compression = options.compression ?? 'zstd';
+    if (typeof root !== 'string' || root.length === 0)
+        throw new Error('session root is unknown');
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        throw new Error('session id is required');
+    if (typeof fromCwd !== 'string' || fromCwd.length === 0)
+        throw new Error('source cwd is required');
+    if (typeof toCwd !== 'string' || toCwd.length === 0)
+        throw new Error('target cwd is required');
+    if (fromCwd === toCwd)
+        throw new Error('source and target cwd are identical');
+    const fromKey = projectKey(fromCwd);
+    const toKey = projectKey(toCwd);
+    if (fromKey === toKey)
+        throw new Error('source and target resolve to the same project directory');
+    const sourceDir = sessionDir(root, fromCwd, sessionId);
+    const targetDir = sessionDir(root, toCwd, sessionId);
+    const found = findGeneration(sourceDir);
+    if ('error' in found) {
+        throw new Error(`${found.error}${found.others !== undefined && found.others.length > 0 ? ` (found: ${found.others.join(', ')})` : ''}`);
+    }
+    const sourcePath = join(sourceDir, found.selected.name);
+    const targetPath = join(targetDir, found.selected.name);
+    const buffer = readFileSync(sourcePath);
+    const compressed = found.selected.compressed;
+    const header = readHeaderFromBuffer(buffer, compressed);
+    if (header === undefined)
+        throw new Error(`cannot read a session header from ${sourcePath}`);
+    if (String(header.id) !== sessionId)
+        throw new Error(`header id ${String(header.id)} does not match requested session ${sessionId}`);
+    if (typeof header.cwd === 'string' && header.cwd !== fromCwd) {
+        throw new Error(`header cwd ${header.cwd} does not match the stored cwd ${fromCwd}`);
+    }
+    const rewritten = rewriteHeaderCwd(buffer, toCwd, { compressed });
+    if (rewritten.rewritten !== true)
+        throw new Error(`cannot rewrite the header cwd: ${rewritten.reason ?? 'unknown reason'}`);
+    let targetExists = false;
+    try {
+        statSync(targetPath);
+        targetExists = true;
+    }
+    catch {
+        targetExists = false;
+    }
+    if (targetExists)
+        throw new Error(`target log already exists (refusing to overwrite): ${targetPath}`);
+    // 目标目录里已有租约文件 = 有人正持有该目录的写租约（或上一次搬迁没搬完）。
+    // 此时再搬会把「已持有的锁」和「日志」拆到两个目录，不如直接拒绝。
+    if (existsSync(join(targetDir, 'session.lock'))) {
+        throw new Error(`target session directory already holds a write lease (refusing to merge): ${join(targetDir, 'session.lock')}`);
+    }
+    const frames = compressed ? scanZstdFrames(buffer) : { frames: [], incomplete: false };
+    if (compressed && frames.incomplete)
+        throw new Error(`source log has an incomplete trailing frame: ${frames.reason}`);
+    return {
+        root,
+        compression,
+        sessionId,
+        fromCwd,
+        toCwd,
+        fromKey,
+        toKey,
+        generation: found.selected,
+        /** 源目录里除 generation 与 `session.lock` 之外的文件（真正会留在原地的）。 */
+        otherFiles: found.others.filter((name) => name !== 'session.lock'),
+        /** 源目录里是否有写租约文件；有则由 {@link applyPlan} 随目录一起搬走。 */
+        leaseFile: found.others.includes('session.lock') ? 'session.lock' : null,
+        otherGenerations: found.all.slice(1).map((entry) => entry.name),
+        sourceDir,
+        targetDir,
+        sourcePath,
+        targetPath,
+        bytesBefore: buffer.length,
+        bytesAfter: rewritten.buffer.length,
+        frameCount: compressed ? frames.frames.length : null,
+        header,
+        rewrittenHeader: rewritten.header,
+        buffer: rewritten.buffer,
+    };
+}
+/** 原子落盘：写 + fsync（崩在中间也不会留下半个文件）。 */
+function writeDurable(path, buffer) {
+    const fd = openSync(path, 'w');
+    try {
+        writeSync(fd, buffer, 0, buffer.length, 0);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * 执行计划。三步改名保证「任何时刻都不存在两份规范名日志」：
+ *   1. 新日志先以临时名写进目标目录（此时还不是 generation）；
+ *   2. 源文件改名成 `*.session-move-old`（源目录里不再有规范名）；
+ *   3. 临时名改成规范名（此刻新日志才生效），随后删掉 `.old` 与空的源目录。
+ * 崩在 2 与 3 之间时，源数据仍在 `.old` 里、新数据仍在 `.tmp` 里，人工可救。
+ *
+ * @param plan - {@link planMove} 的返回值。
+ * @returns 搬迁报告（含 `dshReadbackSafe` 之外的事实字段，供 HTTP/工具直接回话）。
+ */
+export function applyPlan(plan) {
+    const report = {
+        sessionId: plan.sessionId,
+        from: plan.fromCwd,
+        to: plan.toCwd,
+        generation: plan.generation.name,
+        bytesBefore: plan.bytesBefore,
+        bytesAfter: plan.bytesAfter,
+        frames: plan.frameCount,
+        sourcePath: plan.sourcePath,
+        targetPath: plan.targetPath,
+        moved: true,
+    };
+    mkdirSync(plan.targetDir, { recursive: true });
+    const tmpPath = plan.targetPath + TMP_SUFFIX;
+    const parkedPath = plan.sourcePath + PARKED_SUFFIX;
+    writeDurable(tmpPath, plan.buffer);
+    renameSync(plan.sourcePath, parkedPath);
+    renameSync(tmpPath, plan.targetPath);
+    rmSync(parkedPath, { force: true });
+    // 0.2.2 起每个会话目录里有 `session.lock`（POSIX flock，写入句柄整个生命周期持有；
+    // 内核约定这个文件永不删除、靠稳定 inode 判断归属）。搬迁必须把它一起搬过去：
+    // rename 保留 inode，本进程已持有的 flock 会跟着到新路径，仍能挡住第二个写入者；
+    // 留在源目录会得到「源目录有锁、新目录无锁」的半套租约。
+    const leaseName = 'session.lock';
+    const sourceLease = join(plan.sourceDir, leaseName);
+    const targetLease = join(plan.targetDir, leaseName);
+    let leaseMoved = false;
+    if (existsSync(sourceLease)) {
+        if (existsSync(targetLease)) {
+            report.leaseConflict = targetLease;
+        }
+        else {
+            try {
+                renameSync(sourceLease, targetLease);
+                leaseMoved = true;
+            }
+            catch (error) {
+                report.leaseMoveError = messageOf(error);
+            }
+        }
+    }
+    report.leaseMoved = leaseMoved;
+    let removedSourceDir = false;
+    let leftover = [];
+    try {
+        leftover = readdirSync(plan.sourceDir);
+    }
+    catch {
+        leftover = [];
+    }
+    if (leftover.length === 0) {
+        try {
+            rmdirSync(plan.sourceDir);
+            removedSourceDir = true;
+        }
+        catch (error) {
+            report.sourceDirCleanupError = messageOf(error);
+        }
+    }
+    report.removedSourceDir = removedSourceDir;
+    report.leftInSourceDir = leftover;
+    // 落盘之后再读一遍目标文件：确认帧结构可解、header 已是新 cwd。
+    const after = readFileSync(plan.targetPath);
+    const header = readHeaderFromBuffer(after, plan.generation.compressed);
+    report.verifiedHeader = header === undefined
+        ? null
+        : { id: String(header.id), cwd: typeof header.cwd === 'string' ? header.cwd : null, version: header.version };
+    report.verifiedBytes = after.length;
+    report.ok = report.verifiedHeader !== null && report.verifiedHeader.cwd === plan.toCwd;
+    return report;
+}
+/**
+ * 只读校验：目标位置上是否有一份可解析、id/cwd 都对得上的日志。
+ * @param options - `{root, sessionId, cwd, compression}`。
+ * @returns `{ok, header, bytes}` 或 `{ok:false, error}`。
+ */
+export function verifyStoredLog(options) {
+    try {
+        const dir = sessionDir(options.root, options.cwd, options.sessionId);
+        const found = findGeneration(dir);
+        if ('error' in found)
+            return { ok: false, error: found.error };
+        const buffer = readFileSync(join(dir, found.selected.name));
+        const header = readHeaderFromBuffer(buffer, found.selected.compressed);
+        if (header === undefined)
+            return { ok: false, error: 'header is unreadable' };
+        return {
+            ok: String(header.id) === options.sessionId && header.cwd === options.cwd,
+            header: { id: String(header.id), cwd: typeof header.cwd === 'string' ? header.cwd : null },
+            bytes: buffer.length,
+            magic: buffer.length >= 4 && buffer.readUInt32LE(0) === ZSTD_MAGIC ? 'zstd' : 'plain',
+        };
+    }
+    catch (error) {
+        return { ok: false, error: messageOf(error) };
+    }
+}

package/lib/index.js

@@ -0,0 +1,248 @@
+/**
+ * `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 { LOG_LINE_LEVEL_FIRST, LOG_LINE_TIME_FIRST, createFileLogger, resolveVolatileConfig, } from './store/host.js';
+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 { messageOf } from './store/util.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 const API_PREFIX = MOVE_API_PREFIX;
+// ---------------------------------------------------------------------------
+// 插件元信息
+// ---------------------------------------------------------------------------
+/** Cordis 插件名（profile 行 id 是 `session-toolbox`，两者刻意不同名）。 */
+export 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 const inject = ['webServer', 'tools', 'sessions', 'sessionPersistence', 'workspaceRegistry'];
+/** 设置命名空间；与 client 半边 `settings.section` 的 id 必须一致。 */
+export const SETTINGS_NS = 'session-toolbox';
+// ---------------------------------------------------------------------------
+// 配置（两半合并成一份 schema）
+// ---------------------------------------------------------------------------
+/**
+ * 插件配置（两份原配置的**并集**，键名与默认值见 {@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 const Config = z.object({
+    /** 总开关（两半共用）。关掉后两条路由与两个工具都不注册。改它需要重挂本行（非 volatile）。 */
+    enabled: z.boolean().default(true),
+    /** 会话根目录；留空则从 `sessionPersistence.root` 推断（jsonl 后端会暴露它）。搬迁半边用。 */
+    root: z.string().default(''),
+    /**
+     * 删除半边的额外信任 authority（`host` 或 `host:port`，按 `Host` 头解析）。
+     * 原 `dsh-session-admin` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    adminAllowHosts: z.array(String).default([]),
+    /**
+     * 搬迁半边的额外信任 authority（`host` 或 `host:port`，按 socket 的 `remoteAddress`
+     * 精确匹配）。原 `dsh-session-move` 的 `allowHosts`。默认空——只信 loopback。
+     */
+    moveAllowHosts: z.array(String).default([]),
+    /** 是否允许删「属于某个工作区」的会话。默认否——工作区会话通常还想留。 */
+    allowWorkspaceSessions: z.boolean().default(false)
+        .description('允许删除「属于某个工作区」的会话。默认否——工作区会话通常还想留。')
+        .volatile(),
+    /** 是否允许删仍然挂在 Host 进程里的会话（正在浏览/正在跑）。默认否。 */
+    allowLiveSessions: z.boolean().default(false)
+        .description('允许删除仍然挂在 Host 进程里的会话（正在浏览或正在跑）。默认否。')
+        .volatile(),
+    /** 一次调用最多删多少个，防手滑。 */
+    maxBatch: z.number().default(200)
+        .description('一次调用最多删多少个会话，防手滑。默认 200。')
+        .volatile(),
+    /**
+     * 是否在会话标题栏显示「删除当前会话」的垃圾桶图标。**默认开启。**
+     *
+     * 形态刻意是「图标 + 二次确认」而不是带字面标签的按钮：标签会招来点击，而这里
+     * 删的正是你正在用的会话。图标不占字面位置，误点最多弹出一个确认框，离真正删除
+     * 还隔着一步。清理由右侧「会话管理」面板或设置页承担，那是显式挑选动作。
+     *
+     * 这是个 volatile 旋钮：浏览器半边在挂载时问一次 Host（`config` 接口），所以
+     * 改完**刷新页面**就生效——不需要重启 dsh web，也不需要重挂本插件。
+     */
+    headerDeleteButton: z.boolean().default(true)
+        .description('在会话标题栏显示「删除当前会话」的垃圾桶图标。默认开启；关掉后清理由「会话管理」面板/设置页承担。改完刷新页面生效。')
+        .volatile(),
+    /** 是否拒绝搬"正在跑一轮"的会话。默认拒绝——搬运期间它的写入句柄可能落盘。 */
+    refuseRunning: z.boolean().default(true)
+        .description('拒绝搬迁「正在跑一轮」的会话。默认开启——搬运期间它的写入句柄可能落盘。')
+        .volatile(),
+    /** `list` 一次最多返回多少条会话（浏览器半边还要筛选）。 */
+    maxSessions: z.number().default(2000)
+        .description('`list` 一次最多返回多少条会话（浏览器半边还要筛选）。默认 2000。')
+        .volatile(),
+    /**
+     * 项目作用域记忆的条目要不要跟着会话走。**默认 off**。
+     *
+     * 项目记忆是**工作区共享**的（一次写入、那个工作区里所有会话都读），所以把一条
+     * 会话的条目拖到另一个工作区会改变那边的记忆视图——只有"这条会话本来就该在目标
+     * 工作区"（纠正错放）时才该这么做：
+     *   - `off`  ：什么都不做。报告里仍给出**只读预览**（若开启会复制哪几条）。
+     *   - `copy` ：把该会话产出的条目（frontmatter `session:` 精确匹配）复制到目标
+     *              工作区，按文件名去重，源工作区不动。
+     *   - `move` ：同上，但复制后从源工作区移除（不可逆，谨慎）。
+     */
+    memoryFollow: z.string().default('off')
+        .description('项目记忆跟随：off 只给只读预览（默认 / 推荐）；copy 把本会话产出的条目复制到目标工作区；move 复制后从源移除（不可逆）。')
+        .volatile(),
+    /**
+     * 启动时是否做一轮「fork 子会话漏挂工作区」的定向扫描。
+     *
+     * 创建期的 `session/created` 补挂只挡住「Host fork 时就没挂」。记账写进去之后
+     * 又被抹掉的那一类（同机两个 Host 共用 `$DSH_HOME` 时，另一个进程用旧内存快照
+     * 重写 `storages/workspace.json`）只有启动期扫描能补回来，所以默认开启。
+     *
+     * 扫描范围收得很窄：只认带 `parentSession` 的普通 fork 子会话（排除 `origin:
+     * subagent` 与 `delegationDepth > 0`），且父会话已被某个工作区记账、子会话
+     * `cwd` 规范化后等于该工作区路径。刻意 ungrouped 的普通会话/迁移会话不碰。
+     */
+    repairForkChildrenOnBoot: z.boolean().default(true)
+        .description('启动时补挂「fork 子会话漏挂工作区」：只处理父会话已入册、cwd 与工作区一致的普通 fork 子会话。默认开启；挂载期读取，改它需要重挂本行。'),
+});
+/**
+ * 解包 entry 配置里的 `.volatile()` 活引用，并交给 schema 校验补默认值。
+ *
+ * 实现在 `lib/store/host.js`：先解包输入、再校验、最后**再解包一次**——
+ * schemastery 对 `.volatile()` 字段输出的也是活引用，不收敛的话读到的就是 `{ get() }`
+ * 对象（HTTP 面上会变成一个空对象）。
+ * @param raw - entry 配置或普通配置对象。
+ * @returns 普通值配置。
+ */
+export function resolveConfig(raw = {}) {
+    // 解包后的普通对象在这里收敛成 {@link SessionOpsConfig}：schema 的默认值保证了
+    // 每个键都在，但 schemastery 的输出类型不携带这些静态事实，只能就地断言一次。
+    return resolveVolatileConfig(Config, raw);
+}
+/**
+ * 挂载插件：两条路由 + 两个工具。
+ *
+ * 两个半边共用**同一个活配置对象**（见下），各自的信任栅栏读各自的那个键
+ * （`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 function apply(ctx, rawConfig = {}) {
+    /**
+     * 当前生效的配置。
+     *
+     * 对象**身份保持不变**：volatile 字段更新时只把新值 `Object.assign` 进来，于是两个
+     * 半边里所有已经捕获了 `config` 的闭包（HTTP 方法表、工具、信任栅栏、日志）自动
+     * 看到最新值，不需要重挂，也不需要额外的 getter 管道。
+     */
+    const config = { ...resolveConfig(rawConfig) };
+    // 两个半边各自的文件日志（行格式是各自原有的排障产物，见 lib/store/host.js）。
+    const adminLog = createFileLogger(ctx, { name: 'dsh-session-admin', formatLine: LOG_LINE_LEVEL_FIRST });
+    const moveLog = createFileLogger(ctx, { name: 'dsh-session-move', formatLine: LOG_LINE_TIME_FIRST });
+    const logs = [adminLog, moveLog];
+    // volatile 字段写盘后 Loader 原地换引用并补发这个事件：重读一次就能拿到新值。
+    ctx.on('loader/volatile-update', () => {
+        try {
+            Object.assign(config, resolveConfig(rawConfig));
+        }
+        catch (error) {
+            // 表单写盘前会先校验候选值，正常路径不会走到这里；真出错也不能把插件带崩。
+            for (const log of logs)
+                log('warn', `config refresh failed: ${String(error)}`);
+        }
+    });
+    if (config.enabled === false) {
+        for (const log of logs)
+            log('info', 'disabled by config; nothing registered');
+        return;
+    }
+    mountAdmin(ctx, config, adminLog);
+    mountMove(ctx, config, moveLog);
+    // fork 子会话漏挂工作区（实测）：创建期监听 + 启动期定向扫描；只补记账，不改 Host 源码。
+    // 扫描是 fire-and-forget，但绝不留下未处理的 rejection——自愈路径不能影响插件其余部分。
+    const forkSweep = mountForkMembershipRepair(ctx, config, moveLog);
+    if (forkSweep !== undefined) {
+        forkSweep.catch((error) => moveLog('warn', `membership sweep failed: ${messageOf(error)}`));
+    }
+}
+// ---------------------------------------------------------------------------
+// 兼容再导出
+// ---------------------------------------------------------------------------
+/**
+ * 会话存储原语全量再导出（`lib/store/` 的五个模块）：
+ * `dshHome`、`encodeSegment`、`readSessionHeader`、`hasZstd`、`decodeProjectKey` 等。
+ *
+ * 原来的会话存储共享库根入口就是这个形状；合并成单包后保留同一份公开面，
+ * 外部按包名导入的脚本（如 dsh-open-in-dsh）只改包名即可，不必换符号名。
+ * 需要显式分层时也可以用子路径 `dsh-session-ops/store`（见 package.json exports）。
+ */
+export * from './store/index.js';
+// 2026-09-25：本文件是 dsh-session-admin + dsh-session-move 的合并入口
+// （本包就是这两个插件的合并产物；会话存储知识收在 `lib/store/`）。