dsh-vscode-mode 0.1.29 → 0.1.32

package/src/paths.ts

@@ -0,0 +1,284 @@
+/**
+ * dsh-vscode-mode host — 路径常量与动态路径统一出口（PathConst）。
+ * 所有 host 侧文件路径/缓存键/路由前缀从这里取，避免散落内联：
+ * - 静态：插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 工作区级与
+ *   user/ 用户级）、日志根、工作区侧车名、路由前缀、静态资源目录（import.meta.url 派生）
+ * - 动态：每工作区树缓存文件（workspace/<id>/tree.v<schema>.json）、home 解析
+ *   （DSH_HOME → ~/.dsh）
+ * - 清理：缓存 sweep（分级：工作区级按版本/TTL/空目录、用户级按版本/保留期、根级残留）
+ * 纯函数可单测；raw fs 写入与引擎自身插件（settings-file 用 node:fs + DSH_HOME）一致。
+ * 作者 ddj 2026-09-01
+ */
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readdir, rm, stat } from 'node:fs/promises'
+import { RPC_PATH } from './shared/rpc.js'
+
+// --region 常量
+/** 插件 id（也是 .dsh 下插件工作区目录名）。 */
+export const PLUGIN_ID = 'dsh-vscode-mode'
+/** DSH 工作区目录名（默认 home 下）。 */
+export const DSH_DIR_NAME = '.dsh'
+/** home 覆盖环境变量（与引擎 resolveDshHome 一致）。 */
+export const DSH_HOME_ENV = 'DSH_HOME'
+/** 树缓存 schema 版本（文件名携带；版本递增即触发旧版清理）。 */
+export const TREE_CACHE_SCHEMA = 1
+/** 树缓存保留期：超期文件视为废弃（工作区搬迁/废弃残留）。 */
+export const TREE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
+/** 插件缓存目录总预算：超限按 mtime 从旧到新删文件，防任意增长撑爆磁盘（最后兜底）。 */
+export const CACHE_TOTAL_CAP = 200 * 1024 * 1024
+
+/** 工作区根侧车：审查记录（用户数据，随项目走，不迁移）。 */
+export const SIDECAR = '.dsh-edit-review.json'
+/** 工作区根侧车：归档（用户数据）。 */
+export const SIDECAR_ARCHIVE = '.dsh-edit-review-archive.json'
+/** 旧 debug 日志文件名（工作区，迁移后由插件清理）。 */
+export const DEBUG_LOG = '.dsh-edit-review-debug.log'
+/** 旧树缓存 sidecar 名（工作区，迁移后由插件清理；缓存可重建，删除无损）。 */
+export const LEGACY_TREE_SIDECARS = ['.dsh-edit-review-tree.json', '.dsh-vscode-mode-tree.json']
+
+/** RPC 精确路由（shared 定义，这里统一出口）。 */
+export { RPC_PATH }
+/** 路由前缀（兼容性检查用）。 */
+export const ROUTE_PREFIX = '/edrv'
+/** Monaco 静态资源前缀。 */
+export const VENDOR_PREFIX = '/edrv/vendor'
+// --endregion
+
+/** 稳定短哈希（cwd → 缓存文件名段；sha1 截断，跨运行稳定）。 */
+export function hashOf(text: string): string {
+  return createHash('sha1').update(String(text)).digest('hex').slice(0, 16)
+}
+
+// --region DSH 会话定位编码
+/**
+ * 可读安全路径段编码：非安全码位 → ~XXXX 大写十六进制（`~` 本身也转义）。
+ * 与 DSH 引擎 dsh-session-persistence-jsonl 的 encodeSegment 逐字节一致，
+ * 用于从 cwd/id 反推 `~/.dsh/sessions` 下的会话目录，纯函数可单测。
+ * @author ddj 2026年09月02号
+ * @param raw 原始路径段（非空）
+ * @returns 路径安全段（`.`/`..` 特判为 ~002E / ~002E~002E）
+ */
+export function encodeSegment(raw: string): string {
+  if (raw.length === 0) throw new Error('cannot encode an empty path segment')
+  if (raw === '.') return '~002E'
+  if (raw === '..') return '~002E~002E'
+  let out = ''
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i)
+    const ch = String.fromCharCode(code)
+    if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) out += ch
+    else out += '~' + code.toString(16).toUpperCase().padStart(4, '0')
+  }
+  return out
+}
+
+/**
+ * DSH 工作区目录键：cwd → `--<可读键>--`。分隔符（/ \ :）折叠为单个 `-`，
+ * 其余非安全码位转 ~XXXX，`--` 包裹、251 截断。与引擎 projectKey 一致。
+ * @author ddj 2026年09月02号
+ * @param cwd 会话工作区绝对路径（非空）
+ * @returns `~/.dsh/sessions` 下的工作区目录名
+ */
+export function sessionWorkspaceKey(cwd: string): string {
+  if (cwd.length === 0) throw new Error('cannot encode an empty project path')
+  let readable = ''
+  let separatorRun = false
+  for (let i = 0; i < cwd.length; i++) {
+    const code = cwd.charCodeAt(i)
+    const ch = String.fromCharCode(code)
+    if (ch === '/' || ch === '\\' || ch === ':') {
+      if (!separatorRun) readable += '-'
+      separatorRun = true
+    } else if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) {
+      readable += ch
+      separatorRun = false
+    } else {
+      readable += '~' + code.toString(16).toUpperCase().padStart(4, '0')
+      separatorRun = false
+    }
+  }
+  return `--${(readable.replace(/^-+/, '') || 'root').slice(0, 251)}--`
+}
+
+/** DSH 会话目录段：id → 路径安全段（与引擎 encodeSegment 一致）。 */
+export function sessionIdSegment(id: string): string {
+  return encodeSegment(id)
+}
+
+/** DSH 会话根目录（~/.dsh/sessions；引擎 dsh-base 默认 root）。 */
+export function sessionsRoot(home = dshHome()): string {
+  return join(home, 'sessions')
+}
+// --endregion
+
+/**
+ * 解析 DSH home：DSH_HOME（去空白）→ ~/.dsh。
+ * @author ddj 2026年09月01号
+ * @param env 环境映射（缺省 process.env；测试可注入）
+ * @returns 归一化的 DSH home 绝对路径
+ */
+export function dshHome(env: Record<string, string | undefined> = process.env): string {
+  const value = env[DSH_HOME_ENV]
+  if (value && value.trim()) return value
+  return join(homedir(), DSH_DIR_NAME)
+}
+
+/** 插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 与 user/ 两级）。 */
+export function pluginCacheRoot(home = dshHome()): string {
+  return join(home, PLUGIN_ID, 'cache')
+}
+
+/** 工作区级缓存目录：按工作区 id（cwd hash）隔离，换工作区即失效。 */
+export function workspaceCacheDir(workspaceId: string, home = dshHome()): string {
+  return join(pluginCacheRoot(home), 'workspace', workspaceId)
+}
+
+/** 用户级缓存目录（跨工作区共享；当前无实例，预留供全局偏好类缓存使用）。 */
+export function userCacheDir(home = dshHome()): string {
+  return join(pluginCacheRoot(home), 'user')
+}
+
+/** 插件日志根（~/.dsh/dsh-vscode-mode/logs，用户级）。 */
+export function pluginLogRoot(home = dshHome()): string {
+  return join(home, PLUGIN_ID, 'logs')
+}
+
+/** 每工作区树缓存文件（工作区级：workspace/<id>/tree.v<schema>.json，文件名含版本便于 sweep）。 */
+export function treeCacheFile(cwd: string, home = dshHome(), schema = TREE_CACHE_SCHEMA): string {
+  return join(workspaceCacheDir(hashOf(cwd), home), 'tree.v' + schema + '.json')
+}
+
+/** 每工作区 debug 日志文件（用户级日志根下，按 cwd hash 隔离）。 */
+export function debugLogFile(cwd: string, home = dshHome()): string {
+  return join(pluginLogRoot(home), 'debug.' + hashOf(cwd) + '.log')
+}
+
+/** 插件包 assets 目录（import.meta.url 派生；config.imageDir 可覆盖，见 imageDirOf）。 */
+export function assetsDirOf(moduleUrl: string): string {
+  return join(dirname(fileURLToPath(moduleUrl)), '..', 'assets')
+}
+
+/** Monaco AMD 静态目录（随包发布）。 */
+export function vendorDirOf(moduleUrl: string): string {
+  return join(assetsDirOf(moduleUrl), 'vendor')
+}
+
+/** 图标目录：config.imageDir 覆盖优先，否则插件包 assets/。 */
+export function imageDirOf(config: unknown, moduleUrl: string): string {
+  const cfg = config as { imageDir?: unknown } | undefined
+  if (cfg && typeof cfg.imageDir === 'string' && cfg.imageDir) return cfg.imageDir.replace(/\\/g, '/')
+  return assetsDirOf(moduleUrl)
+}
+
+// --region 缓存清理
+/** 树缓存文件名 → schema 版本（不匹配返回 null）。 */
+export function treeSchemaOf(filename: string): number | null {
+  const m = /^tree\.v(\d+)\./.exec(filename)
+  return m ? Number(m[1]) : null
+}
+
+/** 按「schema 版本 + 保留期」清扫某目录内文件（目录级，返回相对路径清单）。 */
+async function sweepDirFiles(dir: string, removed: string[], now: number, dropAll: boolean): Promise<void> {
+  const names = await readdir(dir).catch(() => [])
+  for (const name of names) {
+    const full = join(dir, name)
+    let drop = dropAll
+    if (!drop) {
+      const schema = treeSchemaOf(name)
+      if (schema === null) drop = true // 未知残留
+      else if (schema !== TREE_CACHE_SCHEMA) drop = true // 旧版本
+      else {
+        try {
+          const info = await stat(full)
+          if (now - info.mtimeMs > TREE_RETENTION_MS) drop = true
+        } catch (error) { drop = true }
+      }
+    }
+    if (!drop) continue
+    try {
+      await rm(full, { force: true })
+      removed.push(name)
+    } catch (error) { /* 删除失败静默 */ }
+  }
+}
+
+/** 清扫工作区级缓存：逐工作区目录按版本/TTL 清文件，空目录删除。 */
+async function sweepWorkspaceTier(dir: string, removed: string[], now: number): Promise<void> {
+  const ids = await readdir(dir).catch(() => [])
+  for (const id of ids) {
+    const wsDir = join(dir, id)
+    await sweepDirFiles(wsDir, removed, now, false)
+    const rest = await readdir(wsDir).catch(() => [])
+    if (!rest.length) await rm(wsDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/** 总预算兜底：递归收集全部缓存文件，按 mtime 从旧到新删，直到总大小 ≤ 预算。 */
+async function sweepByTotalCap(root: string, removed: string[], cap: number): Promise<void> {
+  const files: { path: string; mtime: number; size: number }[] = []
+  const walk = async (dir: string): Promise<void> => {
+    const names = await readdir(dir).catch(() => [])
+    for (const name of names) {
+      const full = join(dir, name)
+      try {
+        const info = await stat(full)
+        if (info.isDirectory()) await walk(full)
+        else files.push({ path: full, mtime: info.mtimeMs, size: info.size })
+      } catch (error) { /* 忽略不可读项 */ }
+    }
+  }
+  await walk(root)
+  let total = files.reduce((sum, f) => sum + f.size, 0)
+  files.sort((a, b) => a.mtime - b.mtime)
+  for (const f of files) {
+    if (total <= cap) break
+    try {
+      await rm(f.path, { force: true })
+      total -= f.size
+      removed.push(f.path.slice(root.length + 1))
+    } catch (error) { /* 删除失败静默 */ }
+  }
+}
+
+/**
+ * 清理插件缓存根（分级 + 总预算兜底）：
+ * - 根级残留文件（旧扁平格式/未知）→ 删
+ * - workspace/ 工作区级 → 按「schema 版本 + 保留期」清文件，空目录删除
+ * - user/ 用户级 → 按「schema 版本 + 保留期」清文件
+ * - 总大小超预算 → 按最旧先删（最后防线，防任意增长撑爆磁盘）
+ * best-effort 静默。
+ * @author ddj 2026年09月01号
+ * @param home DSH home（测试可注入）
+ * @param cap 总预算字节数（缺省 CACHE_TOTAL_CAP；测试可注入小预算）
+ * @returns 删除的文件相对路径清单
+ */
+export async function sweepTreeCache(home = dshHome(), cap = CACHE_TOTAL_CAP): Promise<string[]> {
+  const dir = pluginCacheRoot(home)
+  const names = await readdir(dir).catch(() => [])
+  if (!names.length) return []
+  const removed: string[] = []
+  const now = Date.now()
+  await Promise.all(names.map(async (name) => {
+    const full = join(dir, name)
+    try {
+      const info = await stat(full)
+      if (info.isDirectory()) {
+        if (name === 'workspace') await sweepWorkspaceTier(full, removed, now)
+        else if (name === 'user') await sweepDirFiles(full, removed, now, false)
+        else {
+          await rm(full, { recursive: true, force: true })
+          removed.push(name)
+        }
+      } else {
+        await rm(full, { force: true })
+        removed.push(name) // 根级残留（迁移前扁平格式/未知文件）
+      }
+    } catch (error) { /* stat 失败忽略 */ }
+  }))
+  await sweepByTotalCap(dir, removed, cap)
+  return removed
+}
+// --endregion

package/src/perf.ts

@@ -0,0 +1,340 @@
+/**
+ * dsh-vscode-mode host — DSH 会话性能管理（会话卫生 + 体积 stat + 侧车摘要）。
+ * 职责：
+ * - 盘点 ~/.dsh/sessions 全部工作区会话（每会话仅 stat 日志文件，不解压，轻量）；
+ * - 移出/恢复/清除：会话目录在 ~/.dsh/sessions 与 ~/.dsh/sessions-archive 间可逆搬迁；
+ * - 当前会话体积 stat（对话头部指示器用，纯 stat）；
+ * - 侧车摘要：agent/脚本取关键字段，避免整份读 .dsh-edit-review.json 进对话。
+ * 纯函数可单测（路径编码/移出规划）；fs 操作 best-effort 返回逐项结果不抛。
+ * 作者 ddj 2026-09-02
+ */
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve, sep } from 'node:path'
+import { parseSidecar } from './store.js'
+import { recSummary } from './model.js'
+import { SIDECAR, SIDECAR_ARCHIVE, dshHome, sessionIdSegment, sessionWorkspaceKey, sessionsRoot } from './paths.js'
+import type { PerfMoveFailure, PerfMoveItem, PerfSession, PerfTotals, PerfWorkspace, SidecarPerfSummary } from './shared/rpc.js'
+import type { Ctx } from './store.js'
+
+/** 会话日志文件名（zstd 优先，降级纯 jsonl）。 */
+const LOG_NAMES = ['session.jsonl.zstd', 'session.jsonl']
+
+/** 归档根（~/.dsh/sessions-archive，与 sessions 同级，可逆移出的落点）。 */
+export function sessionsArchiveRoot(home = dshHome()): string {
+  return join(home, 'sessions-archive')
+}
+
+/** 会话盘点结果（工作区聚合 + 会话明细 + 汇总）。 */
+export interface SessionInventory {
+  workspaces: PerfWorkspace[]
+  sessions: PerfSession[]
+  totals: PerfTotals
+}
+
+/** 移出规划条件：显式集合或规则（minBytes / olderThanDays）。 */
+export interface MoveCriteria {
+  workspaceKey?: string
+  sessionIds?: string[]
+  minBytes?: number
+  olderThanDays?: number
+}
+
+/** 路径段校验：非空、非 . / ..、不含分隔符与 Windows 非法字符（防 join 逃逸）。 */
+export function validDirName(name: string): boolean {
+  return typeof name === 'string' && name.length > 0 && name !== '.' && name !== '..' && !/[/\\]/.test(name) && !/[:*?"<>|]/.test(name)
+}
+
+/** target 必须落在 root 内（自身或其子路径），防路径穿越。 */
+export function withinDir(target: string, root: string): boolean {
+  const rel = resolve(target)
+  const base = resolve(root)
+  return rel === base || rel.startsWith(base + sep)
+}
+
+/** stat 一个会话目录里的日志文件（首个存在的），缺失 → null。 */
+export async function statSessionLog(sessionDir: string): Promise<{ size: number; mtimeMs: number } | null> {
+  for (const name of LOG_NAMES) {
+    try {
+      const info = await stat(join(sessionDir, name))
+      if (info.isFile()) return { size: info.size, mtimeMs: info.mtimeMs }
+    } catch (error) { /* 尝试下一个日志名 */ }
+  }
+  return null
+}
+
+/**
+ * 盘点 ~/.dsh/sessions：按工作区分组，每会话仅 stat 日志文件体积与 mtime。
+ * 不解压日志（V8 展开成本高），活跃标记由调用方传入后置。
+ * @author ddj 2026年09月02号
+ * @param home DSH home（测试可注入）
+ * @param archive 归档根（默认 sessions-archive；测试可注入）
+ * @returns 工作区聚合（按体积降序）+ 会话明细（按体积降序）+ 汇总
+ */
+export async function scanSessionInventory(home = dshHome(), archive = sessionsArchiveRoot(home)): Promise<SessionInventory> {
+  void archive
+  const root = sessionsRoot(home)
+  const workspaces: PerfWorkspace[] = []
+  const sessions: PerfSession[] = []
+  let totalBytes = 0
+  let totalCount = 0
+  const wsDirs = await readdir(root, { withFileTypes: true }).catch(() => [])
+  for (const ws of wsDirs) {
+    if (!ws.isDirectory() || !validDirName(ws.name)) continue
+    const wsDir = join(root, ws.name)
+    const wsSessions: PerfSession[] = []
+    let wsBytes = 0
+    let minMtime = Number.POSITIVE_INFINITY
+    let maxMtime = 0
+    const sessionDirs = await readdir(wsDir, { withFileTypes: true }).catch(() => [])
+    for (const sd of sessionDirs) {
+      if (!sd.isDirectory()) continue
+      const info = await statSessionLog(join(wsDir, sd.name))
+      if (!info) continue
+      const row: PerfSession = { sessionId: sd.name, workspaceKey: ws.name, bytes: info.size, mtime: info.mtimeMs, active: false }
+      wsSessions.push(row)
+      wsBytes += info.size
+      totalBytes += info.size
+      totalCount += 1
+      if (info.mtimeMs < minMtime) minMtime = info.mtimeMs
+      if (info.mtimeMs > maxMtime) maxMtime = info.mtimeMs
+    }
+    wsSessions.sort((a, b) => b.bytes - a.bytes)
+    sessions.push(...wsSessions)
+    workspaces.push({
+      workspaceKey: ws.name,
+      sessionCount: wsSessions.length,
+      totalBytes: wsBytes,
+      minMtime: Number.isFinite(minMtime) ? minMtime : 0,
+      maxMtime,
+    })
+  }
+  workspaces.sort((a, b) => b.totalBytes - a.totalBytes)
+  return { workspaces, sessions, totals: { workspaces: workspaces.length, sessions: totalCount, totalBytes } }
+}
+
+/** 标记活跃会话（live id 与目录段名双向匹配，兼容编码差异）。 */
+export function markActiveSessions(sessions: PerfSession[], activeIds: Iterable<string>): void {
+  const raw = new Set(activeIds)
+  const encoded = new Set<string>()
+  for (const id of raw) encoded.add(sessionIdSegment(id))
+  for (const s of sessions) {
+    if (raw.has(s.sessionId) || encoded.has(s.sessionId)) s.active = true
+  }
+}
+
+/**
+ * 移出规划（纯函数）：从盘点中按「显式集合」或「规则（minBytes / olderThanDays）」
+ * 圈选可移出会话。活跃会话一律排除；无显式集合且无规则时不选（防误移）。
+ * @author ddj 2026年09月02号
+ * @param inventory 盘点结果
+ * @param criteria 圈选条件
+ * @returns 待移出清单与释放字节
+ */
+export function planMoveOut(inventory: SessionInventory, criteria: MoveCriteria): { items: PerfMoveItem[]; reclaimedBytes: number } {
+  const items: PerfMoveItem[] = []
+  const explicit = Array.isArray(criteria.sessionIds) && criteria.sessionIds.length > 0
+  const cutoff = criteria.olderThanDays ? Date.now() - criteria.olderThanDays * 24 * 60 * 60 * 1000 : 0
+  for (const s of inventory.sessions) {
+    if (s.active) continue
+    if (criteria.workspaceKey && s.workspaceKey !== criteria.workspaceKey) continue
+    if (explicit) {
+      if (!criteria.sessionIds!.includes(s.sessionId)) continue
+    } else {
+      if (criteria.minBytes && s.bytes < criteria.minBytes) continue
+      if (criteria.olderThanDays && s.mtime > cutoff) continue
+      if (!criteria.minBytes && !criteria.olderThanDays) continue
+    }
+    items.push({ workspaceKey: s.workspaceKey, sessionId: s.sessionId, bytes: s.bytes })
+  }
+  return { items, reclaimedBytes: items.reduce((sum, i) => sum + i.bytes, 0) }
+}
+
+/** 移出执行结果。 */
+export interface MoveOutResult {
+  moved: PerfMoveItem[]
+  failures: PerfMoveFailure[]
+  reclaimedBytes: number
+}
+
+/**
+ * 移出会话目录到归档区（同卷 rename，可逆）。活跃会话拒绝；路径越界拒绝；
+ * 逐项 best-effort，成功项写归档 manifest。默认不 dry-run（dryRun 时只校验不搬迁）。
+ * @author ddj 2026年09月02号
+ * @param home DSH home
+ * @param archive 归档根
+ * @param items 待移出清单（来自 planMoveOut 或用户确认）
+ * @param activeIds 活跃会话 id 集合（执行期再校验一次）
+ * @param dryRun 仅校验不搬迁
+ */
+export async function moveOutSessions(home: string, archive: string, items: PerfMoveItem[], activeIds: Iterable<string>, dryRun = false): Promise<MoveOutResult> {
+  const root = sessionsRoot(home)
+  const rawActive = new Set(activeIds)
+  const encodedActive = new Set<string>()
+  for (const id of rawActive) encodedActive.add(sessionIdSegment(id))
+  const isActive = (id: string): boolean => rawActive.has(id) || encodedActive.has(id)
+  const moved: PerfMoveItem[] = []
+  const failures: PerfMoveFailure[] = []
+  for (const item of items) {
+    if (!validDirName(item.workspaceKey)) {
+      failures.push({ workspaceKey: item.workspaceKey, sessionId: item.sessionId, error: '工作区键不合法' })
+      continue
+    }
+    if (isActive(item.sessionId)) {
+      failures.push({ workspaceKey: item.workspaceKey, sessionId: item.sessionId, error: '活跃会话，拒绝移出' })
+      continue
+    }
+    const seg = sessionIdSegment(item.sessionId)
+    const src = join(root, item.workspaceKey, seg)
+    const dst = join(archive, item.workspaceKey, seg)
+    if (!withinDir(src, root) || !withinDir(dst, archive)) {
+      failures.push({ workspaceKey: item.workspaceKey, sessionId: item.sessionId, error: '路径越界，拒绝执行' })
+      continue
+    }
+    if (dryRun) {
+      try {
+        const info = await stat(src)
+        if (info.isDirectory()) moved.push({ ...item, bytes: (await statSessionLog(src))?.size ?? item.bytes })
+        else failures.push({ workspaceKey: item.workspaceKey, sessionId: item.sessionId, error: '源目录不存在' })
+      } catch (error) {
+        failures.push({ workspaceKey: item.workspaceKey, sessionId: item.sessionId, error: '源目录不存在' })
+      }
+      continue
+    }
+    try {
+      await mkdir(dirname(dst), { recursive: true })
+      await rename(src, dst)
+      const bytes = (await statSessionLog(dst))?.size ?? item.bytes
+      moved.push({ ...item, bytes })
+    } catch (error) {
+      failures.push({ workspaceKey: item.workspaceKey, sessionId: item.sessionId, error: String(error) })
+    }
+  }
+  if (moved.length && !dryRun) await appendMoveManifest(archive, moved)
+  return { moved, failures, reclaimedBytes: moved.reduce((sum, i) => sum + i.bytes, 0) }
+}
+
+/** 恢复单个会话：归档 → sessions。目标已存在则拒绝（不覆盖）。 */
+export async function restoreSession(home: string, archive: string, workspaceKey: string, sessionId: string): Promise<{ ok: boolean; error?: string }> {
+  if (!validDirName(workspaceKey)) return { ok: false, error: '工作区键不合法' }
+  const seg = sessionIdSegment(sessionId)
+  const root = sessionsRoot(home)
+  const src = join(archive, workspaceKey, seg)
+  const dst = join(root, workspaceKey, seg)
+  if (!withinDir(src, archive) || !withinDir(dst, root)) return { ok: false, error: '路径越界，拒绝执行' }
+  try {
+    await stat(src)
+  } catch (error) {
+    return { ok: false, error: '归档中不存在该会话' }
+  }
+  try {
+    await stat(dst)
+    return { ok: false, error: '目标位置已存在同名会话' }
+  } catch (error) { /* 目标不存在，可恢复 */ }
+  try {
+    await mkdir(dirname(dst), { recursive: true })
+    await rename(src, dst)
+    return { ok: true }
+  } catch (error) {
+    return { ok: false, error: String(error) }
+  }
+}
+
+/** 清除归档区早于 N 天的会话（破坏性，仅限归档区）。 */
+export async function purgeArchive(archive: string, olderThanDays: number): Promise<{ removed: number; reclaimedBytes: number }> {
+  const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000
+  let removed = 0
+  let reclaimedBytes = 0
+  const wsDirs = await readdir(archive, { withFileTypes: true }).catch(() => [])
+  for (const ws of wsDirs) {
+    if (!ws.isDirectory()) continue
+    const wsDir = join(archive, ws.name)
+    const sessionDirs = await readdir(wsDir, { withFileTypes: true }).catch(() => [])
+    for (const sd of sessionDirs) {
+      if (!sd.isDirectory()) continue
+      const info = await statSessionLog(join(wsDir, sd.name))
+      if (!info || info.mtimeMs > cutoff) continue
+      try {
+        await rm(join(wsDir, sd.name), { recursive: true, force: true })
+        removed += 1
+        reclaimedBytes += info.size
+      } catch (error) { /* 删除失败跳过 */ }
+    }
+  }
+  return { removed, reclaimedBytes }
+}
+
+/** 当前会话持久化体积（对话头部指示器用）：仅 stat，近零成本。 */
+export async function sessionSizeOf(home: string, cwd: string, sessionId: string): Promise<{ bytes: number; exists: boolean }> {
+  const dir = join(sessionsRoot(home), sessionWorkspaceKey(cwd), sessionIdSegment(sessionId))
+  for (const name of LOG_NAMES) {
+    try {
+      const info = await stat(join(dir, name))
+      if (info.isFile()) return { bytes: info.size, exists: true }
+    } catch (error) { /* 尝试下一个日志名 */ }
+  }
+  return { bytes: 0, exists: false }
+}
+
+/**
+ * 侧车摘要：返回活跃记录数、每文件 pending 计数、归档体积。
+ * agent/脚本取关键字段即可，不必整份读 .dsh-edit-review.json（避免大对象进对话）。
+ * @author ddj 2026年09月02号
+ * @param ctx DSH host 上下文（fs 服务）
+ * @param cwd 工作区路径（null 时返回空摘要）
+ */
+export async function sidecarSummaryOf(ctx: Ctx, cwd: string | null): Promise<SidecarPerfSummary> {
+  const fs = ctx.get('fs')
+  const summary: SidecarPerfSummary = { active: 0, pendingByFile: [], archiveBytes: 0 }
+  if (!fs || !cwd) return summary
+  try {
+    const text = await fs.readText(await fs.resolve(SIDECAR, { cwd }))
+    const data = parseSidecar(text)
+    const recs = data?.workspaces?.[cwd]?.records
+    if (recs) {
+      const byFile = new Map<string, number>()
+      let active = 0
+      for (const rec of Object.values(recs)) {
+        if (rec.archived) continue
+        active += 1
+        const sm = recSummary(rec)
+        if (sm.pending > 0 && rec.path) byFile.set(rec.path, (byFile.get(rec.path) ?? 0) + sm.pending)
+      }
+      summary.active = active
+      summary.pendingByFile = [...byFile.entries()].map(([path, pending]) => ({ path, pending })).sort((a, b) => b.pending - a.pending)
+    }
+    try {
+      const info = await fs.stat(await fs.resolve(SIDECAR_ARCHIVE, { cwd }))
+      summary.archiveBytes = info?.size ?? 0
+    } catch (error) { /* 归档缺失忽略 */ }
+  } catch (error) { /* sidecar 不可读返回空摘要 */ }
+  return summary
+}
+
+/** 归档 manifest 条目。 */
+interface MoveManifestEntry { at: string; workspaceKey: string; sessionId: string }
+
+/** 归档 manifest（可逆移出的索引，供恢复/审计）。 */
+interface MoveManifest { version: 1; items: MoveManifestEntry[] }
+
+/** 解析归档 manifest（损坏/缺失 → 空）。 */
+function parseMoveManifest(text: string | null): MoveManifest {
+  if (!text) return { version: 1, items: [] }
+  try {
+    const data = JSON.parse(text) as MoveManifest
+    return { version: 1, items: Array.isArray(data.items) ? data.items : [] }
+  } catch (error) {
+    return { version: 1, items: [] }
+  }
+}
+
+/** 追加移出记录到归档 manifest（best-effort，失败不影响主流程）。 */
+async function appendMoveManifest(archive: string, items: PerfMoveItem[]): Promise<void> {
+  try {
+    const file = join(archive, '.manifest.json')
+    const prev = parseMoveManifest(await readFile(file, 'utf8').catch(() => null))
+    const at = new Date().toISOString()
+    for (const item of items) prev.items.push({ at, workspaceKey: item.workspaceKey, sessionId: item.sessionId })
+    await mkdir(archive, { recursive: true })
+    await writeFile(file, JSON.stringify(prev, null, 2), 'utf8')
+  } catch (error) { /* manifest 写失败静默 */ }
+}