dsh-manage-session 0.4.8 → 0.5.3

package/src/host/index/sync.ts

@@ -0,0 +1,286 @@
+/**
+ * Watermark-driven incremental sync between the live-preferred sessionQuery
+ * corpus and the independent switch-search index.
+ *
+ * One pass lists the logical corpus, diffs stored `version` watermarks, and
+ * re-reads only new or changed sessions. Per-session failures are isolated and
+ * reported; one broken log never stalls the whole sync.
+ */
+import type { SwitchIndexEngine } from './engine.ts'
+import { extractTitleFromEvents, type SwitchRawEvent } from './extract.ts'
+
+/** 标题折叠的分块大小（一次 readTitleSnapshots 的 id 数上限,防整批一坏全坏）。 */
+const TITLE_CHUNK = 50
+
+/** The sessionQuery faces the sync reads (structural mirrors). */
+export interface SwitchSyncSessionQuery {
+  listSessions(): Promise<readonly { header: { id: string; version: number; createdAt?: number; cwd?: string } }[]>
+  readSession(sessionId: string): Promise<{
+    session: { id: string; version: number; createdAt?: number; cwd?: string }
+    events: readonly SwitchRawEvent[]
+  }>
+  readTitleSnapshots?(sessionIds: readonly string[]): Promise<readonly {
+    status: 'fulfilled' | 'rejected'
+    value?: { session: { id: string }; title?: { title: string } }
+  }[]>
+}
+
+/** Live sync progress reported to the status endpoint. */
+export interface SwitchSyncState {
+  /** What the syncer is doing right now. */
+  state: 'idle' | 'syncing' | 'error'
+  /** Epoch ms of the last completed pass. */
+  lastSyncAt: number
+  /** Sessions currently in the index. */
+  indexed: number
+  /** Sessions seen in the corpus at the last pass. */
+  total: number
+  /** Sessions re-read in the last pass. */
+  updated: number
+  /** Per-session failures from the last pass. */
+  failures: { sessionId: string; error: string }[]
+  /** Last pass error (whole-pass abort), if any. */
+  error?: string
+}
+
+/**
+ * The official archive-set face (workspaceRegistry mirror): read-only.
+ * Resolved lazily per pass — the registry may mount after this plugin.
+ */
+export interface SwitchArchiveSource {
+  readonly archivedSessionIds: readonly string[]
+}
+
+/**
+ * One watermark syncer bound to one open engine. `poll()` is re-entrant-safe:
+ * overlapping calls collapse into the running pass.
+ */
+export class SwitchWatermarkSync {
+  private running: Promise<SwitchSyncState> | undefined
+  private readonly state: SwitchSyncState = {
+    state: 'idle',
+    lastSyncAt: 0,
+    indexed: 0,
+    total: 0,
+    updated: 0,
+    failures: [],
+  }
+
+  /**
+   * @param readSessionFromFile - 可选的**文件级兜底读取器**（管家 health 侧的
+   * 多帧 zstd 读取器）：sessionQuery.readSession 对某些会话（典型:归档会话,
+   * 或服务面退化）失败时改读转录文件。返回 undefined 表示文件也不可用。
+   */
+  constructor(
+    private readonly engine: SwitchIndexEngine,
+    private readonly sessionQuery: SwitchSyncSessionQuery,
+    private readonly readArchiveSource?: () => SwitchArchiveSource | undefined,
+    private readonly log?: (msg: string) => void,
+    private readonly readSessionFromFile?: (sessionId: string) => Promise<{
+      session: { id: string; version: number; createdAt?: number; cwd?: string }
+      events: readonly SwitchRawEvent[]
+    } | undefined>,
+    /**
+     * 第三标题源（可选）:官方投影缓存里的 title 行。事件流没有 session/title
+     * 的老会话,快照服务又整片不可用时,这是最后兜底。
+     */
+    private readonly readProjectionTitle?: (sessionId: string) => string,
+  ) {
+
+  }
+
+  /**
+   * 读取一个会话的日志:服务面优先,失败落文件兜底。两条路都失败时抛最后
+   * 一个错误,由调用方按会话隔离记失败。
+   */
+  private async readSessionLog(header: { id: string; version: number; createdAt?: number; cwd?: string }): Promise<{
+    session: { id: string; version: number; createdAt?: number; cwd?: string }
+    events: readonly SwitchRawEvent[]
+  }> {
+    try {
+      return await this.sessionQuery.readSession(header.id)
+    } catch (serviceError) {
+      if (this.readSessionFromFile === undefined) throw serviceError
+      const fromFile = await this.readSessionFromFile(header.id)
+      if (fromFile !== undefined) {
+        this.log?.(`session ${header.id}: sessionQuery read failed, served from transcript file (${String(serviceError instanceof Error ? serviceError.message : serviceError)})`)
+        return fromFile
+      }
+      throw serviceError
+    }
+  }
+
+  /** Current progress snapshot (cloned). */
+  snapshot(): SwitchSyncState {
+    return { ...this.state, failures: [...this.state.failures] }
+  }
+
+  /**
+   * Fold titles for an explicit id set without running a full pass.
+   *
+   * Used by the `session/title` event listener so a rename lands immediately
+   * rather than at the next poll. It deliberately leaves watermarks alone: a
+   * title-only refresh can never make the index claim content it has not read,
+   * and the next poll still re-ingests the session off its bumped version.
+   * Safe for unknown ids — the header write is a no-op when no row exists.
+   * @param sessionIds - sessions whose titles should be re-folded.
+   */
+  async refreshTitles(sessionIds: readonly string[]): Promise<void> {
+    await this.backfillTitles(sessionIds)
+  }
+
+  /**
+   * Run one incremental pass (or await the running one).
+   * @returns the state after the pass completes.
+   */
+  poll(): Promise<SwitchSyncState> {
+    if (this.running !== undefined) return this.running
+    this.running = this.runPass().finally(() => {
+      this.running = undefined
+    })
+    return this.running
+  }
+
+  private async runPass(): Promise<SwitchSyncState> {
+    this.state.state = 'syncing'
+    const passStart = Date.now()
+    try {
+      const records = await this.sessionQuery.listSessions()
+      this.state.total = records.length
+      // 官方归档集合：纯 flag 翻转（R1 合表复用语义——归档保留 docs,恢复不重灌）。
+      // Registry absent -> no-op。
+      const archiveSource = this.readArchiveSource?.()
+      const archivedSet = new Set(archiveSource?.archivedSessionIds ?? [])
+      this.engine.setArchived(archivedSet)
+      const failures: { sessionId: string; error: string }[] = []
+      let updated = 0
+      const changedIds: string[] = []
+      for (const record of records) {
+        const header = record.header
+        const existing = this.engine.getSession(header.id)
+        // 归档与活跃同一读取通路：readSession 对归档会话是 replay-validate 不激活
+        // （宿主 session-query 保证）。归档正文因此入索引（可被 archived 域检索）。
+        if (existing !== undefined && existing.version === header.version) continue
+        changedIds.push(header.id)
+        try {
+          const log = await this.readSessionLog(header)
+          this.engine.upsertSession({
+            sessionId: header.id,
+            version: header.version,
+            cwd: log.session.cwd ?? header.cwd ?? '',
+            updatedAt: log.session.createdAt ?? header.createdAt ?? 0,
+            // 标题基础层:事件流白拿（归档 id 也能拿到）;快照折叠只做精修。
+            title: extractTitleFromEvents(log.events),
+            events: log.events,
+            // 新行插入时带上归档标记（ON CONFLICT 不动旧行的 flag,翻转仍归
+            // setArchived）—— 免掉"插行要等下一轮 setArchived 才翻 flag"的单轮滞后。
+            archived: archivedSet.has(header.id),
+          })
+          updated += 1
+        } catch (err) {
+          failures.push({ sessionId: header.id, error: String(err instanceof Error ? err.message : err) })
+        }
+      }
+      // 归档覆盖:某些宿主线的 listSessions 可能不含归档会话 —— 归档集合里的
+      // id 若还没有索引行,这里显式补齐（readSession 对归档是 replay-validate,
+      // 失败时走文件兜底）。
+      for (const archivedId of archivedSet) {
+        if (this.engine.getSession(archivedId) !== undefined) continue
+        try {
+          const log = await this.readSessionLog({ id: archivedId, version: -1 })
+          this.engine.upsertSession({
+            sessionId: archivedId,
+            version: log.session.version,
+            cwd: log.session.cwd ?? '',
+            updatedAt: log.session.createdAt ?? 0,
+            title: extractTitleFromEvents(log.events),
+            events: log.events,
+            archived: true,
+          })
+          updated += 1
+        } catch (err) {
+          failures.push({ sessionId: archivedId, error: `archived: ${String(err instanceof Error ? err.message : err)}` })
+        }
+      }
+      // Drop sessions that vanished from the corpus —— 但**归档集合里的行不删**：
+      // 某些宿主线的 listSessions 可能过滤归档,归档集合才是删除真值（purge 会把
+      // id 从归档数组里摘掉,彼时下一轮自然清行）。
+      const corpusIds = new Set(records.map(record => record.header.id))
+      for (const indexed of this.engine.listIndexedSessions()) {
+        if (!corpusIds.has(indexed.sessionId) && !archivedSet.has(indexed.sessionId)) {
+          this.engine.removeSession(indexed.sessionId)
+        }
+      }
+      await this.backfillTitles(changedIds)
+      // 空标题扫尾:重建行/老会话可能没有 session/title 事件,快照精修后仍空
+      // 的行用投影缓存兜底。每轮封顶 100 行,标题落地后集合自然收缩。
+      const emptyTitles = this.engine.listIndexedSessions()
+        .filter(session => session.title.trim() === '')
+        .map(session => session.sessionId)
+        .slice(0, 100)
+      if (emptyTitles.length > 0) {
+        await this.backfillTitles(emptyTitles)
+        let filled = 0
+        for (const id of emptyTitles) {
+          const row = this.engine.getSession(id)
+          if (row !== undefined && row.title.trim() !== '') continue
+          const fromProjection = this.readProjectionTitle?.(id) ?? ''
+          if (fromProjection.trim() !== '') {
+            this.engine.updateSessionHeader({ sessionId: id, title: fromProjection })
+            filled += 1
+          }
+        }
+        if (filled > 0) this.log?.(`title sweep: ${filled}/${emptyTitles.length} filled from projection cache`)
+      }
+      this.state.updated = updated
+      this.state.failures = failures
+      this.state.indexed = this.engine.countSessions()
+      this.state.lastSyncAt = Date.now()
+      this.state.state = 'idle'
+      this.state.error = undefined
+      this.log?.(`sync pass: scanned=${this.state.total} updated=${updated} archived=${archivedSet.size} failures=${failures.length} indexed=${this.state.indexed} duration=${Date.now() - passStart}ms driver=${this.engine.driverLabel}`)
+    } catch (err) {
+      this.state.state = 'error'
+      this.state.error = String(err instanceof Error ? err.message : err)
+      this.log?.(`sync pass FAILED: ${this.state.error}`)
+    }
+    return this.snapshot()
+  }
+
+  /**
+   * Fold latest titles for changed sessions into the index header rows.
+   *
+   * beta.4 教训:整批一次调用,任何一个坏 id（典型:归档 id）让整个 promise
+   * reject,catch 一吞就是**全部**标题丢失。改为分块 + 块失败时逐 id 重试 ——
+   * 单点坏 id 最多损失它自己的精修标题（入索引时的 extractTitleFromEvents
+   * 基础层仍然在）。
+   */
+  private async backfillTitles(sessionIds: readonly string[]): Promise<void> {
+    const readTitles = this.sessionQuery.readTitleSnapshots
+    if (readTitles === undefined || sessionIds.length === 0) return
+    const ids = [...new Set(sessionIds)]
+    const foldOne = (observation: { status: 'fulfilled' | 'rejected'; value?: { session: { id: string }; title?: { title: string } } }): void => {
+      if (observation.status !== 'fulfilled' || observation.value === undefined) return
+      const title = observation.value.title?.title
+      // 归档行的标题同样折叠（归档会话仍可改名,索引标题要跟上）。
+      if (typeof title === 'string' && title.trim().length > 0) {
+        this.engine.updateSessionHeader({ sessionId: observation.value.session.id, title })
+      }
+    }
+    for (let start = 0; start < ids.length; start += TITLE_CHUNK) {
+      const chunk = ids.slice(start, start + TITLE_CHUNK)
+      try {
+        const observations = await readTitles(chunk)
+        observations.forEach(foldOne)
+      } catch {
+        // 整块失败 → 逐 id 重试,坏 id 只损失自己。
+        for (const id of chunk) {
+          try {
+            const observations = await readTitles([id])
+            observations.forEach(foldOne)
+          } catch { /* 该 id 的精修标题放弃,基础层标题仍在 */ }
+        }
+      }
+    }
+  }
+}

package/src/host/registry/archive-registry.ts

@@ -0,0 +1,317 @@
+/**
+ * 替换官方 workspace 注册表的管家子类(P1 服务替换,AM 架构轻量版)。
+ *
+ * cordis.patch.yml 禁用官方 `workspace` 行并插入本类(`dsh-manage-session/registry`):
+ * - 归档/取消归档/记账完全继承官方行为(setState 自带持久化,免重启);
+ * - 覆写 sessionKnown / indexHeader 挂**墓碑**:本进程已物理删除的会话不被
+ *   stale `persistence.list()` 重新编入索引、不被重新写回归档集合;
+ * - 冷复用探针:其他进程以同 id 重建且日志身份不同(createdAt/cwd)的新会话
+ *   撤墓碑放行,避免误挡;
+ * - `deleteSession`:全痕删除七步 —— 实时 flush/detach → 等投影写尾 → 删缓存
+ *   文件 → subagent 后代级联(fork 不级联)→ 清 spill → 删转录目录(越界防护)
+ *   → 记账清理(归档集合 + 工作区成员表)+ 父类内存索引遗忘。物理成功才提交
+ *   记账,失败保留现场可重试。
+ *
+ * 已知边界:官方投影缓存服务无 delete API,缓存行走"等写尾 + 删文件"直删
+ * (官方缓存 fail-soft 自愈兜底);whenIdle 只覆盖本类感知的在途写。
+ *
+ * 类型策略(AM 同款):官方把 sessionKnown/indexHeader/requireState 等声明为
+ * TS private,子类用结构化镜像接口松化基类构造器 —— 运行时成员逐一存在
+ * (0.1.7/0.2.0 实证),逐段 try/catch 容忍老线形状漂移。
+ */
+import { rmSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Context } from 'cordis'
+import { WorkspaceRegistry } from '@deepseek-ai/dsh-workspace'
+import { dirKey, isSafeChild, locateSessionUsage, projCacheRootFor, sessionsRootFor } from '../history/purge.ts'
+
+/** 官方 sessions 服务面(结构化镜像,全线存在)。 */
+interface RegistrySessionsFace {
+  get?(id: string): { id?: string; header?: StewardHeaderLike } | undefined
+  list?(): { id?: string; header?: StewardHeaderLike }[]
+  flush?(live: unknown): Promise<void>
+  liveEntryFor?(live: unknown): unknown
+  detachEntered?(entry: unknown): void
+}
+
+/** 会话头部子集(父类内部 headers / persistence.list 的公共形状)。 */
+interface StewardHeaderLike {
+  id?: string
+  createdAt?: number
+  cwd?: string
+  parentSession?: string
+  origin?: string
+}
+
+/**
+ * 父类运行时面的结构化镜像:private 成员在此公开化。成员按 0.1.7/0.2.0
+ * 实测形状声明;调用点逐段 try/catch,老线缺失时删除路径报错可重试。
+ */
+interface StewardRegistryCompat {
+  ctx: Context
+  headers?: Map<string, StewardHeaderLike>
+  sessionPaths?: Map<string, unknown>
+  invalidSessionPaths?: Set<string>
+  entities?: Map<string, { record?: unknown }>
+  sessionKnown(id: string): Promise<boolean>
+  indexHeader(header: StewardHeaderLike): Promise<void>
+  listStoredHeaders?(): Promise<StewardHeaderLike[]>
+  requireState?(): { archivedSessionIds?: string[]; workspaceIds?: readonly string[] }
+  setState?(state: unknown): Promise<void>
+  requireTable?(): {
+    get?(id: string): { sessionIds?: string[] } | undefined
+    update?(id: string, fn: (current: { sessionIds: string[] }) => unknown): Promise<unknown>
+  }
+}
+
+type StewardWorkspaceConstructor = { new (ctx: Context): StewardRegistryCompat }
+
+const TOMBSTONE_LIMIT = 4096
+
+export const StewardWorkspaceRegistry = class extends (WorkspaceRegistry as unknown as StewardWorkspaceConstructor) {
+  static inject = ['storageDomain', 'sessionPersistence']
+
+  /** 本进程已物理删除的会话墓碑(FIFO 上限淘汰,宁多挡不错放)。 */
+  deletedSessionIds = new Set<string>()
+  deletedSessionOrder: string[] = []
+  /** 被删生命周期的日志身份:冷复用探针区分"同 id 新会话"与 stale list()。 */
+  deletedIdentities = new Map<string, { createdAt?: number; cwd?: string }>()
+  /** 转录/缓存文件定位根(apply 装配时注入;缺失时文件删除跳过并记日志)。 */
+  dshHome = ''
+
+  private log(message: string): void {
+    try {
+      (this.ctx as unknown as { logger?: { info?: (m: string) => void; warn?: (m: string) => void } })
+        .logger?.info?.(`[session-steward] ${message}`)
+    } catch { /* 日志绝不破坏宿主 */ }
+  }
+
+  /** ── 墓碑层:覆写父类的已知性判定与头部索引 ── */
+
+  async sessionKnown(id: string): Promise<boolean> {
+    const sessions = this.ctx.get('sessions') as { get?: (id: string) => unknown } | undefined
+    if (sessions?.get?.(id) !== undefined && sessions.get!(id) !== null) {
+      this.clearTombstone(id)
+      return true
+    }
+    if (this.deletedSessionIds.has(id)) return await this.coldReuseKnown(id)
+    return await super.sessionKnown(id)
+  }
+
+  /** 冷复用探针:同 id 重建且日志身份不同 → 撤墓碑重新编入;身份不可考则保守维持未知。 */
+  private async coldReuseKnown(id: string): Promise<boolean> {
+    const deleted = this.deletedIdentities.get(id)
+    if (deleted === undefined) return false
+    const headers = await this.allStoredHeaders()
+    const header = headers.find(item => item.id === id)
+    if (header === undefined) return false
+    if (header.createdAt === deleted.createdAt && header.cwd === deleted.cwd) return false
+    this.clearTombstone(id)
+    try {
+      await this.indexHeader(header)
+    } catch { /* 重编入失败不阻断已知性 */ }
+    return true
+  }
+
+  async indexHeader(header: StewardHeaderLike): Promise<void> {
+    if (header.id !== undefined && this.deletedSessionIds.has(header.id)) return
+    await super.indexHeader(header)
+  }
+
+  clearTombstone(sessionId: string): void {
+    this.deletedSessionIds.delete(sessionId)
+    this.deletedIdentities.delete(sessionId)
+    const idx = this.deletedSessionOrder.indexOf(sessionId)
+    if (idx >= 0) this.deletedSessionOrder.splice(idx, 1)
+  }
+
+  /** ── 全痕删除 ── */
+
+  /** 逐会话入口:任何一步失败都返回 ok:false + error,记账保留现场可重试。 */
+  async deleteSession(sessionId: string): Promise<{ ok: boolean; skipped?: boolean; error?: string }> {
+    try {
+      return await this.deleteCore(sessionId)
+    } catch (err) {
+      const message = String(err instanceof Error ? err.message : err)
+      this.log(`delete ${sessionId} failed: ${message}`)
+      return { ok: false, error: message }
+    }
+  }
+
+  private async deleteCore(sessionId: string, descendantHeaders?: StewardHeaderLike[]): Promise<{ ok: boolean; skipped?: boolean }> {
+    if (!(await this.sessionKnown(sessionId))) {
+      // 未知会话:清掉可能残留的记账(归档集合/工作区表),不留僵尸 id。
+      await this.forgetBookkeeping(sessionId)
+      this.log(`delete ${sessionId}: unknown session, residual bookkeeping cleared`)
+      return { ok: true, skipped: true }
+    }
+    const sessions = this.ctx.get('sessions') as RegistrySessionsFace | undefined
+    const live = sessions?.get?.(sessionId)
+    const deletedHeader = this.headers?.get(sessionId) ?? live?.header
+    if (live !== undefined) {
+      // 持久化屏障先行:flush 过的会话不再持有打开的日志文件,目录删除不竞争。
+      await sessions!.flush!(live)
+      const entry = sessions!.liveEntryFor!(live)
+      sessions!.detachEntered!(entry)
+    }
+    // 投影缓存:等 dispose 写尾落盘,再直删缓存文件(官方服务无 delete API)。
+    const projCache = this.ctx.get('sessionProjectionCache') as { whenIdle?: () => Promise<void> } | undefined
+    await projCache?.whenIdle?.()
+    this.deleteProjectionCacheFile(sessionId)
+    await this.deleteDescendants(sessionId, descendantHeaders)
+    await this.cleanSpill(sessionId)
+    this.removeTranscriptDirectory(sessionId)
+    // 物理工件删除成功后才提交记账清理;失败时保留归档标记/成员表以便重试。
+    await this.forgetBookkeeping(sessionId)
+    this.forgetIndexedSession(sessionId)
+    if (deletedHeader !== undefined) {
+      this.deletedIdentities.set(sessionId, { createdAt: deletedHeader.createdAt, cwd: deletedHeader.cwd })
+    }
+    try {
+      (this.ctx as unknown as { emit?: (name: string, payload?: unknown) => void }).emit?.('api-session/removed', sessionId)
+    } catch { /* 通知失败不阻断删除结论 */ }
+    return { ok: true }
+  }
+
+  /** subagent 后代级联:live 列表优先,stored headers 兜底;fork(parentSession 有值但 origin 非 subagent)不级联。 */
+  private async deleteDescendants(sessionId: string, storedHeaders?: StewardHeaderLike[]): Promise<void> {
+    try {
+      const descendants: string[] = []
+      const sessions = this.ctx.get('sessions') as RegistrySessionsFace & { list?: () => { id?: string; header?: StewardHeaderLike }[] } | undefined
+      const listed = typeof sessions?.list === 'function' ? sessions.list() : []
+      for (const session of listed) {
+        const header = session?.header
+        if (header?.parentSession === sessionId && header.origin === 'subagent' && typeof session.id === 'string') {
+          descendants.push(session.id)
+        }
+      }
+      if (descendants.length === 0) {
+        const headers = storedHeaders ?? await this.allStoredHeaders()
+        for (const header of headers) {
+          if (header.parentSession === sessionId && header.origin === 'subagent' && typeof header.id === 'string') {
+            descendants.push(header.id)
+          }
+        }
+      }
+      for (const child of descendants) {
+        if (child === sessionId) continue
+        await this.deleteCore(child, storedHeaders)
+      }
+      if (descendants.length > 0) this.log(`delete ${sessionId}: cascaded ${descendants.length} subagent descendant(s)`)
+    } catch (err) {
+      this.log(`descendant cascade for ${sessionId} failed: ${String(err instanceof Error ? err.message : err)}`)
+    }
+  }
+
+  /** 父类 listStoredHeaders(0.1.5+)→ sessionPersistence.list 兜底 → 空数组。 */
+  private async allStoredHeaders(): Promise<StewardHeaderLike[]> {
+    try {
+      const listed = await this.listStoredHeaders?.()
+      if (Array.isArray(listed)) return listed
+    } catch { /* 老线无此方法 → 兜底 */ }
+    try {
+      const persistence = this.ctx.get('sessionPersistence') as { list?: () => Promise<StewardHeaderLike[]> } | undefined
+      const listed = await persistence?.list?.()
+      if (Array.isArray(listed)) return listed
+    } catch { /* 读不到就当空 */ }
+    return []
+  }
+
+  /** spill 目录直删(sessionDir(root, sessionId) — spill-local 包自己的签名)。 */
+  private async cleanSpill(sessionId: string): Promise<void> {
+    try {
+      const spill = this.ctx.get('spillStore') as { root?: string } | undefined
+      if (spill === undefined || typeof spill.root !== 'string') return
+      const spec = '@deepseek-ai/dsh-spill-local'
+      const mod = (await import(spec)) as { sessionDir?: (root: string, id: string) => string }
+      if (typeof mod.sessionDir !== 'function') return
+      rmSync(mod.sessionDir(spill.root, sessionId), { recursive: true, force: true })
+    } catch (err) {
+      this.log(`spill cleanup for ${sessionId} failed: ${String(err instanceof Error ? err.message : err)}`)
+    }
+  }
+
+  /** 转录目录删除:文件扫描定位(与文件路径同一套越界防护)。 */
+  private removeTranscriptDirectory(sessionId: string): void {
+    if (this.dshHome === '') {
+      this.log(`transcript deletion for ${sessionId} skipped: dshHome not wired`)
+      return
+    }
+    const usage = locateSessionUsage([sessionId], this.dshHome)
+    const entry = usage.get(sessionId)
+    if (entry?.dir === undefined) return
+    if (!isSafeChild(sessionsRootFor(this.dshHome), entry.dir, 2)) {
+      this.log(`refusing out-of-root transcript path: ${entry.dir}`)
+      return
+    }
+    rmSync(entry.dir, { recursive: true, force: true })
+  }
+
+  /** 缓存文件直删:双候选文件名(带/不带 session- 前缀,与 purge.ts 同纪律)。 */
+  private deleteProjectionCacheFile(sessionId: string): void {
+    if (this.dshHome === '') return
+    const cacheRoot = projCacheRootFor(this.dshHome)
+    for (const name of [`${sessionId}.json`, `${dirKey(sessionId)}.json`]) {
+      const candidate = join(cacheRoot, name)
+      if (!isSafeChild(cacheRoot, candidate, 1)) continue
+      try {
+        rmSync(candidate, { force: true })
+      } catch { /* 竞态:文件刚被删 */ }
+    }
+  }
+
+  /** 记账清理:归档集合(setState)+ 工作区成员表(requireTable)。逐段容错。 */
+  private async forgetBookkeeping(sessionId: string): Promise<void> {
+    try {
+      const state = this.requireState?.()
+      if (state?.archivedSessionIds !== undefined && this.setState !== undefined
+        && Array.isArray(state.archivedSessionIds) && state.archivedSessionIds.includes(sessionId)) {
+        await this.setState({
+          ...state,
+          archivedSessionIds: state.archivedSessionIds.filter(id => id !== sessionId),
+        })
+      }
+    } catch (err) {
+      this.log(`archive-set bookkeeping cleanup for ${sessionId} failed: ${String(err instanceof Error ? err.message : err)}`)
+    }
+    try {
+      const table = this.requireTable?.()
+      const state = this.requireState?.()
+      const workspaceIds = state?.workspaceIds
+      if (table?.update === undefined || !Array.isArray(workspaceIds)) return
+      for (const workspaceId of workspaceIds) {
+        const record = table.get?.(workspaceId)
+        if (record === undefined || !Array.isArray(record.sessionIds) || !record.sessionIds.includes(sessionId)) continue
+        const next = await table.update(workspaceId, (current: { sessionIds: string[] }) => ({
+          ...current,
+          sessionIds: current.sessionIds.filter(id => id !== sessionId),
+        }))
+        const entity = this.entities?.get(workspaceId)
+        if (entity !== undefined) entity.record = next
+      }
+    } catch (err) {
+      this.log(`workspace bookkeeping cleanup for ${sessionId} failed: ${String(err instanceof Error ? err.message : err)}`)
+    }
+  }
+
+  /** 父类内存索引遗忘 + 墓碑登记(FIFO 上限淘汰)。 */
+  private forgetIndexedSession(sessionId: string): void {
+    if (!this.deletedSessionIds.has(sessionId)) {
+      this.deletedSessionIds.add(sessionId)
+      this.deletedSessionOrder.push(sessionId)
+    }
+    while (this.deletedSessionOrder.length > TOMBSTONE_LIMIT) {
+      const oldest = this.deletedSessionOrder.shift()
+      // id 自身被挤出队列时保留在集合中:宁多挡不错放。
+      if (oldest !== undefined && oldest !== sessionId) {
+        this.deletedSessionIds.delete(oldest)
+        this.deletedIdentities.delete(oldest)
+      }
+    }
+    try { this.headers?.delete(sessionId) } catch { /* 内部形状漂移容忍 */ }
+    try { this.sessionPaths?.delete?.(sessionId) } catch { /* 同上 */ }
+    try { this.invalidSessionPaths?.delete?.(sessionId) } catch { /* 同上 */ }
+  }
+} as unknown as typeof WorkspaceRegistry
+
+export type StewardWorkspaceRegistry = WorkspaceRegistry